canonical_url: https://yycode.net/docs/en/recommended-global-rules
lang: en
updated_at: 2026-07-04T13:33:48.616Z
source_html: https://yycode.net/docs/en/recommended-global-rules

# Personal AGENTS.md Global Rules

> This is a set of global rules I have personally refined for Claude code and codex. Put it in `AGENTS.md` or `CLAUDE.md` at the project root. For beginners, it is a very convenient rule set.

---

## Design Philosophy: Progressive Spec

The core of this rule set is **Progressive Specification**: requirements of different complexity use workflows of different depth, avoiding over-design for simple tasks while establishing sufficient constraints for complex ones.

Simply put: **accidental complexity should be compressed as much as possible; only essential complexity deserves management effort.**

---

## Coding Workflow Overview

| Requirement size | Workflow |
|---------|------|
| Simple (change a field, fix a bug) | Execute directly, no Spec needed |
| Medium (3+ steps, with architecture decisions) | Write a lightweight Spec, then code after HARD-GATE confirmation |
| Complex (cross-module, multi-system) | Full Propose -> Apply -> Review |

Core rules:
- **No Spec, No Code** — for medium or larger complexity, no code changes without a Spec
- **HARD-GATE** — after the Spec is written, wait for explicit user confirmation before coding
- **Reverse Sync** — if a deviation is found during execution, fix the Spec first, then the code

The freedom level of each stage is explicit: research can explore freely, solution design can be imaginative, but **the execution stage has zero freedom**. Strictly follow the plan, and stop to ask immediately if there is a deviation.

---

## Execution Characteristics of Each AI

This rule set works very well in **Codex**. It generally follows the workflow strictly and behaves stably when constraints are clear.

**Claude** has more of its own "ideas": sometimes it proactively does extra things without explicit instruction, or interprets rules flexibly. Its execution is more flexible than expected. Overall, it is less "obedient" than Codex, but it can be more useful in creative tasks and solution design.

> Each has strengths and weaknesses. Pairing them by task type works better.

---

## Full Rules (Copyable)

```
# Language

- Default language for conversation with me is Chinese

# Notes

By default, do not create any new documentation files.
Do not automatically generate README.md, design docs, usage guides, architecture docs, etc.
Only when I explicitly ask to "write docs / generate README / write documentation" may you create or modify documentation.

# Code Style

- Code must be written clearly with Chinese comments. All functions and key logic must have comments

---

# Workflow Orchestration

## 1. Progressive Spec: complexity on demand

Different requirement complexity should use workflows of different depth; accidental complexity should be compressed as much as possible:

| Requirement size | Workflow |
|---------|------|
| Simple (change a field, fix a bug) | Execute directly, no Spec needed |
| Medium (3+ steps, with architecture decisions) | Write a lightweight Spec, code after HARD-GATE |
| Complex (cross-module, multi-system) | Full Propose -> Apply -> Review |

**Three iron rules of Spec** (triggered only for medium or higher complexity):
1. **No Spec, No Code** — without a Spec, code changes are not allowed
2. **Spec is Truth** — if Spec and code conflict, the code is wrong
3. **Reverse Sync** — when deviations are found during execution, fix the Spec first, then the code

**HARD-GATE**: After the complete Spec is generated, wait for explicit user confirmation before coding. Before confirmation, all code modification actions are forbidden.

**Research must have sources**: when describing the current code state, every conclusion must cite file path + function name. No "usually speaking" or unsupported inference.

**Segmented Spec confirmation**: do not generate the full Spec in one shot. Output it in sections (current-state analysis -> functionality -> risks and decisions), and wait for user confirmation after each section before continuing. The earlier direction issues are found, the cheaper they are to correct.

## 2. Plan Node Default

- For any medium or higher complexity task, enter plan mode
- Stop and re-plan immediately if something goes wrong; do not force progress
- Plan mode also applies to verification steps, not only the build phase

## 3. Subagent Strategy

- Use subagents heavily to keep the main context window clean
- Give research, exploration, and parallel analysis to subagents
- Use subagents for more computation on complex problems
- Each subagent should do exactly one thing and stay focused

## 4. Execution Freedom Curve

| Stage | Freedom | Principle |
|------|--------|------|
| Research | Medium | Explore freely, but conclusions must cite code sources |
| Solution design | High | Imagine fully, present options + recommendation |
| Planning | Low | Be precise down to file paths and function signatures |
| Execution | Zero | Strictly follow the plan; stop and ask immediately if there is a deviation |
| Acceptance | Medium | Check freely, but conclusions need evidence |

## 5. Self-Improvement Loop

- After every user correction: write the pattern to `tasks/lessons.md`
- Write rules to prevent the same mistake from recurring
- At the start of each session, review relevant rules in lessons
- For valuable pitfalls and domain discoveries, proactively suggest recording them in the project knowledge base

## 6. Verification Iron Rule

- A task must not be marked complete before verification
- Verifiable evidence must be shown (build output / test results / run logs)
- Statements like "should be fine" without evidence are forbidden
- Compare behavior before and after changes when necessary

## 7. Demand Elegance (moderate)

- For non-simple changes, pause and ask: "Is there a more elegant way?"
- If a solution feels hacky: "Knowing this, implement the elegant solution"
- Directly perform simple and obvious fixes; do not over-design

## 8. Autonomous Bug Fixing

- If given a bug report, go fix it; do not wait for step-by-step guidance
- Point to logs, errors, or failing tests, then solve it
- Do not require the user to switch context
- If CI tests fail, proactively fix them

---

# Task Management

1. **Write a plan first**: write the plan to `tasks/todo.md` using checkable task items
2. **Execute after confirmation**: for medium or higher complexity tasks, implement only after the HARD-GATE
3. **Track progress**: mark each item immediately after completion
4. **Explain changes**: provide a high-level explanation at each step
5. **Record results**: add a review section at the end of `tasks/todo.md`
6. **Capture lessons**: after user correction, update `tasks/lessons.md`

---

# Core Principles

- **Simplicity First**: keep every change as simple as possible. Minimize impact scope.
- **No Laziness**: find the root cause, do not patch around it; use senior developer standards.
- **Minimal Impact**: change only necessary code and avoid introducing new issues.
- **Intent separation**: handle only one intent at a time. Do not mix exploration, decision, execution, and review.
```