From 5dc50ce08eadb465af70706ee56ffeb48eac4a02 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E9=A3=8E=E9=9B=A8=E7=81=AB?= <l156486648@163.com>
Date: Fri, 13 Mar 2026 18:06:07 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E8=A1=A5=E5=85=85=E6=B5=8B=E8=AF=95?=
 =?UTF-8?q?=E7=AD=96=E7=95=A5=E8=AF=B4=E6=98=8E?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 AGENTS.md | 36 ++++++++++++++++++++++++++++++++++++
 README.md | 10 ++++++++++
 2 files changed, 46 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..3832a7b
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,36 @@
+# Repository Guidelines
+
+## Branch Intent
+
+- Keep the main product branch clean. Do not leave temporary architecture validation pages, routes, or demo-only shells in the merge target.
+- Use a dedicated `spike/<topic>` branch for architecture checks such as router experiments, Tailwind pipeline verification, layout trials, or framework integration smoke tests.
+- Treat spike work as disposable by default. The spike proves a decision; it is not automatically part of the product.
+
+## Architecture Validation Workflow
+
+1. Create a `spike/<topic>` branch.
+2. Keep temporary code isolated under `src/spikes/<topic>/`.
+3. If a route is needed, use a clearly temporary path such as `/__spike/<topic>`.
+4. Add only the smallest tests needed to lock the intended rule or render contract.
+5. After the validation is complete, merge back only reusable residue:
+   - naming or routing conventions
+   - reusable scaffolding
+   - minimal contract tests
+   - docs or skills that capture the rule
+6. Remove one-off validation pages and routes from the final merge candidate unless they provide lasting regression value.
+
+## Routing Rules
+
+- `/` is reserved for the product-facing homepage or dashboard.
+- Temporary validation routes must never become the default app entry.
+- Do not couple the homepage to spike-only experiments.
+
+## Testing Rules
+
+- Add tests early, but keep them proportional.
+- On the main product branch, prefer minimal contract tests that protect stable architecture decisions.
+- Put broad visual verification, temporary smoke pages, and exploratory state matrices on spike branches instead of the mainline.
+
+## Skills
+
+- The local skill `.agents/skills/add-test-page/SKILL.md` is for temporary validation work and should be applied on spike branches, not on the main product branch.
diff --git a/README.md b/README.md
index d57b3e0..d1cc705 100644
--- a/README.md
+++ b/README.md
@@ -39,6 +39,16 @@ It is an **Agentic Engineering foundation**:
 - modules can scale with it
 - rules can evolve without breaking the core structure
 
+## Architecture Validation Workflow
+
+This repo keeps architecture experiments separate from the main product branch.
+
+- Use `spike/<topic>` branches for temporary validation pages, smoke routes, layout probes, and style-chain experiments.
+- Keep spike code isolated under `src/spikes/<topic>/` and temporary routes under paths such as `/__spike/<topic>`.
+- Do not turn `/` into a test page. The homepage stays product-facing.
+- After a spike proves the direction, merge back only reusable outcomes: conventions, scaffolding, minimal contract tests, and documentation.
+- Delete one-off validation pages and routes before merging unless they have clear long-term regression value.
+
 ## Tech stack
 
 - Vue 3