# Repository Guidelines & Rules

## Need to obey
- Use Chinese when we chat.
- Always base on First Principle.
- Unless the user explicitly says not to, close each completed change by staging, committing, and pushing the current worktree.
- Use rg to replace grep.

---

## 12-rule template (Extended to 15 Rules)

These rules apply to every task in this project.
Bias: caution over speed on non-trivial work. Use judgment on trivial tasks.

### Rule 1 — Think Before Coding
State assumptions explicitly. If uncertain, ask rather than guess.
Present multiple interpretations when ambiguity exists.
Push back when a simpler approach exists.
Stop when confused. Name what's unclear.

### Rule 2 — Simplicity First
Minimum code that solves the problem. Nothing speculative.
No features beyond what was asked. No abstractions for single-use code.
Test: would a senior engineer say this is overcomplicated? If yes, simplify.

### Rule 3 — Surgical Changes
Touch only what you must. Clean up only your own mess.
Don't "improve" adjacent code, comments, or formatting.
Don't refactor what isn't broken. Match existing style.

### Rule 4 — Goal-Driven Execution
Define success criteria. Loop until verified.
Don't follow steps. Define success and iterate.
Strong success criteria let you loop independently.

### Rule 5 — Use the model only for judgment calls
Use me for: classification, drafting, summarization, extraction.
Do NOT use me for: routing, retries, deterministic transforms.
If code can answer, code answers.

### Rule 6 — Token budgets are not advisory
Per-task: 4,000 tokens. Per-session: 30,000 tokens.
If approaching budget, summarize and start fresh.
Surface the breach. Do not silently overrun.

### Rule 7 — Surface conflicts, don't average them
If two patterns contradict, pick one (more recent / more tested).
Explain why. Flag the other for cleanup.
Don't blend conflicting patterns.

### Rule 8 — Read before you write
Before adding code, read exports, immediate callers, shared utilities.
"Looks orthogonal" is dangerous. If unsure why code is structured a way, ask.

### Rule 9 — Tests verify intent, not just behavior
Tests must encode WHY behavior matters, not just WHAT it does.
A test that can't fail when business logic changes is wrong.

### Rule 10 — Checkpoint after every significant step
Summarize what was done, what's verified, what's left.
Don't continue from a state you can't describe back.
If you lose track, stop and restate.

### Rule 11 — Match the codebase's conventions, even if you disagree
Conformance > taste inside the codebase.
If you genuinely think a convention is harmful, surface it. Don't fork silently.

### Rule 12 — Fail loud
"Completed" is wrong if anything was skipped silently.
"Tests pass" is wrong if any were skipped.
Default to surfacing uncertainty, not hiding it.

### Rule 13 — Zero Tolerance for Regression
Never compromise or disable existing features when adding new code. Identify and protect all legacy and concurrent behaviors in the modified area.
Verify backward compatibility: when editing a module, run regression checks on all related existing flows.
If a structural or design conflict is detected, stop immediately and raise it for user clarification instead of silently averaging or ignoring it.

### Rule 14 — Memory & Skill Consolidation
- **Action Required**: At the end of every task, evaluate if there is any long-term engineering value to preserve (e.g., hidden configurations, environment traps, specific interactive commands, complex build workflows).
- **Consolidation**:
  - For new areas, define a new skill in the custom skills directory (e.g., `.agents/skills/<skill-name>/SKILL.md`).
  - For existing topics, update the corresponding skill file with progressive disclosure to keep instructions compact.
  - **Skill Formatting Specification**:
    1. **Frontmatter (YAML)**: Every `SKILL.md` must contain proper `name` and `description` frontmatter at the very top. This is the only triggering mechanism for the skill routing.
    2. **Strict Offloading**: Keep the `SKILL.md` body concise (under 300 lines). Offload large JSON schemas, database layouts, troubleshooting steps, and detailed test scripts to `references/` subdirectory.
    3. **Checklist**: Validate the completed skill via `./scripts/quick_validate.py <path>` or perform manual self-checks before committing changes.
  - **Filter**: Only record reusable setup, debugging, and integration guidelines. Do NOT record temporary features or business-specific logic.

### Rule 15 — Definition of Done & Delivery Standards
- **DoD (Definition of Done)**: A task is NOT complete until all the following criteria are met:
  1. **Compilation & Tests**: Code compiles without errors, and the test suite passes 100% with zero silent skips.
  2. **Acceptance & Deployment**: If core logic or integration boundaries change, execute project-specific deployment/build scripts to ensure physical artifacts are updated.
  3. **Git Cleanliness**: Working tree must be clean (no temp debug files left untracked), changes committed, and pushed to remote.
- **Delivery Artifact**: Your final response MUST outline:
  - **What was modified**: A bullet list of edited files and their core change logic.
  - **How it was verified**: The exact commands run and a deterministic statement of runtime behaviors observed.
  - **Skills Updated**: Clear declaration of updated custom skills or explicit rationale for why no changes were required.