Cyrene_v2/AGENTS.md

Cyrene v2 开发铁律（AGENTS.md）

本文件是项目级开发铁律，由运行环境在每次工作会话时自动注入。即使发生上下文压缩/丢失，以下约束仍会强制生效。必须遵守，违反即偏离。

1. 先读设计，再写代码

• 动任何代码前：先读 DevDocs/开发时间线.md（当前里程碑 + §3 功能状态清单），确定这一步属于哪个里程碑/功能。
• 具体功能实现：先读对应 DevDocs/design/*.md，按其规格实现，不得自行发挥（design/01~13 是权威设计）。

2. 按里程碑推进，不跳步、不漂移

• 严格按 M0 → M12 顺序。每个功能的依赖与归属见时间线 §2/§3。
• 不得「想到什么做什么」。新需求/新想法：先写入设计或时间线清单，再开发，不脱离清单。
• 上下文压缩后：先读 DevDocs/工作小结.md 恢复锚点，再继续，不得凭印象跳走。

3. 每阶段审查并勾选

• 阶段完成：后端 go build ./... + go vet ./... + go test ./... 全绿；前端 tsc --noEmit + vite build 通过。
• 在 DevDocs/开发时间线.md §3 勾选状态：✅ 已完成 / ⚠️ 未完成/阻塞（⚠️ 必须记录原因与延后里程碑）。
• 与 DevDocs/design/* 比对：不一致时以设计为准——先改设计文档或修正代码，不允许带着偏离堆叠。

4. 改动前确认归属

• 修改任一文件/功能前，明确它在哪个里程碑、对应哪份 design 文档；改完同步该文档（若设计变了）。

5. 实时同步工作小结

• 每完成一步，更新 DevDocs/工作小结.md：当前里程碑 / 进度 / 已完成+未完成 / 关键决策 / 变更日志。

6. 小步提交 + 频繁验证

• 小粒度 commit；每步 build/test 通过再提交；提交信息按 Git 规范（feat/fix/refactor/docs/chore，scope 用模块名）。

7. 不信任记忆，信任清单

• 关键决策、架构铁律、用户红线（如身份识别靠元数据、不靠提示词）都记录在 DevDocs/工作小结.md 的「关键决策」区；压缩后回读，不得丢失。

8. 上下文保护：可并行项交给后台子代理，主会话当监工

• 相互独立、不依赖主会话开放状态的开发任务（如 M0 地基各件、层 1 并行件），用 Agent(run_in_background=true) 派后台子代理并行实现。
• 主会话只当监工：等子代理回报 → 验收（go build/vet/test）→ 更新 工作小结.md + 时间线 → 小步 commit → 派下一批。不在主会话里重复子代理已做的搜索/实现。
• 子代理 prompt 必须自包含：写清目标、已知信息、精确文件路径、必须遵守的编码约束（02-development-constraints.md）、验收命令；不要让它去搜已经知道的东西。
• 只有真正独立才并行；有依赖的串行。避免两个子代理同时改 go.mod/go.sum——若都要改，指定其中一个负责或先把依赖拉好。
• 目的：防主会话上下文超限触发压缩；压缩后靠本文件 + 工作小结.md 恢复锚点，继续当监工。