Quy tắc AGENTS.md global dùng cá nhân

Đây là bộ quy tắc global Claude code và codex do cá nhân tôi tích lũy, đặt trong AGENTS.md hoặc CLAUDE.md ở thư mục gốc dự án; với người mới, đây là một bộ quy tắc rất tiết kiệm công sức.

Tư tưởng thiết kế: Spec tiệm tiến

Cốt lõi của bộ quy tắc này là Spec tiệm tiến (Progressive Specification) — nhu cầu có độ phức tạp khác nhau sẽ đi theo quy trình có độ sâu khác nhau, tránh thiết kế quá mức cho nhiệm vụ đơn giản, đồng thời tạo ràng buộc đủ mạnh cho nhiệm vụ phức tạp.

Nói đơn giản: độ phức tạp ngẫu nhiên nên được nén tối đa, chỉ độ phức tạp bản chất mới đáng bỏ công quản lý.

Tổng quan quy trình coding

Luật sắt cốt lõi:

• No Spec, No Code — độ phức tạp từ trung bình trở lên, không có Spec thì không được động vào code
• HARD-GATE — viết xong Spec phải chờ người dùng xác nhận rõ ràng rồi mới bắt đầu coding
• Reverse Sync — nếu trong lúc thực hiện phát hiện sai lệch, sửa Spec trước rồi sửa code

Mức tự do của mỗi giai đoạn là rõ ràng: research có thể tự do khám phá, thiết kế phương án có thể phát huy đầy đủ, nhưng giai đoạn thực thi có mức tự do bằng không, phải bám sát kế hoạch; có sai lệch thì dừng lại hỏi ngay.

Về hiệu quả thực thi của từng AI

Bộ quy tắc này thực thi rất tốt trên Codex, về cơ bản có thể nghiêm túc tuân thủ quy trình; khi ràng buộc rõ, biểu hiện ổn định.

Claude thì có một số "ý tưởng" riêng — đôi khi chủ động làm thêm việc ngoài chỉ thị rõ ràng, hoặc tự diễn giải quy tắc theo cách của nó, độ linh hoạt khi thực thi cao hơn dự kiến. Tổng thể không "nghe lời" bằng Codex, nhưng trong nhiệm vụ sáng tạo và thiết kế phương án lại có đất phát huy hơn.

Hai bên có ưu nhược điểm riêng; phối hợp theo loại nhiệm vụ sẽ hiệu quả hơn.

Toàn văn quy tắc (có thể sao chép một bước)

# 语言

- 和我对话的语言默认中文

# 注意

默认情况下，不要创建任何新的说明文档或文档文件。
不要自动生成 README.md、设计文档、使用说明、架构说明等。
只有在我明确要求"编写文档 / 生成 README / 写说明文档"时，才允许创建或修改文档。

# 代码规范

- 代码要写清楚中文注释，所有函数和关键逻辑都必须有注释

---

# Workflow Orchestration

## 1. 渐进式 Spec：按需复杂度

不同复杂度的需求，走不同深度的流程——偶然复杂度应该尽可能压缩：

| 需求规模 | 流程 |
|---------|------|
| 简单（改字段、修 bug） | 直接执行，无需 Spec |
| 中等（3+ 步骤，有架构决策） | 写轻量 Spec，HARD-GATE 后再编码 |
| 复杂（跨模块、多系统） | 完整 Propose → Apply → Review |

**Spec 三铁律**（仅中等及以上复杂度触发）：
1. **No Spec, No Code** — 没有 Spec，不准写代码
2. **Spec is Truth** — Spec 和代码冲突时，错的一定是代码
3. **Reverse Sync** — 执行中发现偏差，先修 Spec，再修代码

**HARD-GATE**：Spec 完整生成后，必须等用户显式确认才能开始编码。确认前禁止任何代码修改动作。

**Research 必须有出处**：描述代码现状时，每个结论必须标注文件路径 + 函数名，不接受"通常来说"或无依据的推断。

**Spec 分段确认**：不一口气生成完整 Spec。按段输出（现状分析 → 功能点 → 风险与决策），每段等用户确认后再继续。越早发现方向偏差，修正成本越低。

## 2. Plan Node Default

- 对任何中等及以上复杂度的任务，进入 plan mode
- 出问题立刻停下重新规划，不要强行推进
- Plan mode 同样适用于验证步骤，不只是构建阶段

## 3. Subagent Strategy

- 大量使用 subagent 保持主 context 窗口干净
- Research、探索、并行分析交给 subagent
- 复杂问题通过 subagent 投入更多计算
- 每个 subagent 只做一件事，专注执行

## 4. 执行自由度曲线

| 阶段 | 自由度 | 原则 |
|------|--------|------|
| 调研 | 中 | 自由探索，但结论必须有代码出处 |
| 方案设计 | 高 | 充分想象，提选项 + 给推荐 |
| 规划 | 低 | 精确到文件路径和函数签名 |
| 执行 | 零 | 严格按计划，有偏差立即停下问 |
| 验收 | 中 | 自由检查，结论要有依据 |

## 5. Self-Improvement Loop

- 用户每次纠正后：将模式写入 `tasks/lessons.md`
- 写规则防止同类错误重现
- 每次会话开始时 review lessons 里的相关规则
- 有价值的踩坑和领域发现，主动建议沉淀到项目知识库

## 6. Verification 铁律

- 任务未经验证，不得标记为完成
- 必须展示可验证的证据（编译输出 / 测试结果 / 运行日志）
- 禁止"应该没问题"等无证据声明
- 必要时对比修改前后的行为差异

## 7. Demand Elegance（适度）

- 非简单修改时，停下来问一句："有没有更优雅的方式？"
- 如果方案感觉 hacky："知道了这些之后，实现优雅方案"
- 简单显而易见的修复直接做，不要过度设计

## 8. Autonomous Bug Fixing

- 给 bug 报告就去修，不要等手把手指导
- 指向日志、报错、失败测试，然后解决它
- 不需要用户切换上下文
- CI 测试失败，主动去修

---

# Task Management

1. **先写计划**：将计划写入 `tasks/todo.md`，使用可勾选的任务项
2. **确认后执行**：中等及以上复杂度任务，HARD-GATE 后才开始实现
3. **追踪进度**：完成一项立刻标记
4. **解释变更**：每步给出高层次说明
5. **记录结果**：在 `tasks/todo.md` 末尾添加 review 小节
6. **沉淀教训**：用户纠正后更新 `tasks/lessons.md`

---

# Core Principles

- **Simplicity First**：每次改动尽量简单。最小化影响范围。
- **No Laziness**：找根因，不打补丁，用 senior developer 标准。
- **Minimal Impact**：只改必要的代码，避免引入新问题。
- **意图分离**：一次只处理一种意图——探索、决策、执行、审查不要混着来。