AGENTS.md

这个仓库面向长时运行的 coding-agent 工作流。保持这个文件简短，把它当成“唯一事实来源”文档的入口和路由层，而不是一个不断膨胀的大说明书。

开工流程

改代码前先做这些事：

1. 用 pwd 确认仓库根目录。
2. 读取 ARCHITECTURE.md，理解当前系统地图和硬性依赖规则。
3. 读取 docs/QUALITY_SCORE.md，先知道最弱的产品领域和架构层。
4. 读取 docs/PLANS.md，再打开当前要执行的 active plan。
5. 读取相关的 docs/product-specs/ 规格文档。
6. 跑这个仓库约定的 bootstrap 与验证路径。
7. 如果基础验证先失败，先修 baseline，再加新范围。

路由地图

• ARCHITECTURE.md：领域地图、分层模型、依赖规则
• docs/design-docs/index.md：设计决策与核心信念
• docs/product-specs/index.md：当前产品行为与验收目标
• docs/PLANS.md：计划生命周期与执行计划规则
• docs/QUALITY_SCORE.md：产品领域与架构层健康度
• docs/RELIABILITY.md：运行信号、benchmark、重启要求
• docs/SECURITY.md：密钥、沙箱、数据和外部动作规则
• docs/FRONTEND.md：UI 约束、设计系统规则、可访问性检查

工作约定

• 一次只围绕一个有边界的计划或功能切片工作。
• 不能只靠读代码就宣布完成，必须有可运行证据。
• 只要改了行为，就同步更新对应的产品、计划或可靠性文档。
• 如果某类 review feedback 反复出现，把它升级成机械规则、检查或 linter，不要一直在聊天里重复解释。
• 生成物放进 docs/generated/，外部 reference 放进 docs/references/。
• 需要更多细节时，优先补小而新的文档，而不是继续把这个文件写长。

完成定义

一个改动只有在以下条件都满足时才算完成：

• 目标行为已实现
• 要求的验证真的跑过
• 证据已经挂到相关 plan 或质量文档里
• 受影响的文档仍然是最新的
• 仓库能按标准启动路径干净重启

收尾

结束会话前：

1. 更新当前 active execution plan。
2. 如果产品领域或架构层有明显变化，更新 docs/QUALITY_SCORE.md。
3. 如果有延期处理的债务，记到 docs/exec-plans/tech-debt-tracker.md。
4. 已完成的计划及时移到 docs/exec-plans/completed/。
5. 保证仓库可重启，并留下清晰的下一步动作。