项目上下文
帮助用户决定并记录项目的稳定规则，每条规则归入其所属的文件。用户来做决策：你负责阅读、提出具体的选项和草稿。
它替代了 Spec Kit 的 constitution.md。其所有内容都有了更合适的归宿：
| 内容 | 文件 | 阅读者 |
|---|---|---|
| 技术栈、分层、依赖规则、不可协商的原则、术语表 | docs/ARCHITECTURE.md | 用户和代理；spec-to-plan 和 review-spec 会检查这些原则 |
| 质量、分支、提交、PR、审查、AI 使用 | CONTRIBUTING.md | 用户（代理通过链接访问） |
| 每个架构决策的理由及被舍弃的备选方案 | docs/adr/NNNN-*.md | 两者，按需查看 |
| 命令、边界、非显而易见的约定、文档地图 | AGENTS.md（以及引用 @AGENTS.md 的 CLAUDE.md） | 代理，每次会话 |
| 如何报告漏洞、代理策略 | SECURITY.md | 用户 |
模板位于 assets/en/（英文）和 assets/es/（西班牙文）。使用项目文档所使用的语言；如果不清楚，询问用户。每个模板在其开头的注释中说明了如何填写。
规则
- 不要重复。 如果某内容已存在于
pyproject.toml、CI 或 linter 中，链接到它；不要复制它。如果一个原则出现在两个文件中，它们最终会相互矛盾：原则只存在于ARCHITECTURE.md中。 AGENTS.md要简短： 不超过 150 行。它是一张链接地图，不包含具体内容。对于每一行：“如果我删除它，代理会出错吗？”。如果不会，就删除。- 可以用工具检查的内容就用工具检查。 对于每个原则，询问如何验证（lint、import-linter、测试、CI、审查）并记录在其列中。
- 没有易变内容： 没有冲刺状态或 TODO。这些内容放在项目管理工具或
docs/plans/中。 - 展示每个文件的全文（或差异，如果文件已存在），并且仅在用户批准后才写入。
流程
1. 阅读项目
在提问之前，先阅读：清单文件（pyproject.toml、package.json、go.mod……）、README.md、任何现有的上下文文件、.github/workflows/、linter 配置和文件夹结构。利用你所发现的内容来提出建议，而不是提出开放式问题。
确定模式并告知用户：
- 绿地（没有代码或几乎没有）：
ARCHITECTURE.md是规定性的，描述“将如何”。 - 棕地：
ARCHITECTURE.md是描述性的，描述“当前如何”。理想情况放入 ADR 和工具的限制器中。如果上下文文件已存在，只询问差距并提出差异。 - 从
constitution.md迁移：根据上表分配其内容，并提出删除它或将其缩减为链接的建议。
2. 按轮次访谈
一次一个类别。对于每个问题，提供具体的选项（A、B、“保持待定”、“其他”）。如果文件已经回答了问题，则请求确认而不是询问。如果某个类别不适用（例如，没有数据库），则跳过它并说明原因。每轮结束时，总结已决定的内容。
| 轮次 | 决策内容 | 目的地 |
|---|---|---|
| 1. 目的 | 项目是什么以及其范围；类型（应用、服务、库、CLI） | ARCHITECTURE.md §1、README.md |
| 2. 技术栈与架构 | 语言、框架、持久化、基础设施；层次或模块以及它们可以导入什么 | ARCHITECTURE.md §2–4、每个架构决策一个 ADR |
| 3. 不可协商的原则 | 5-10 条稳定、可验证的规则：为什么，以及每条规则如何被检查 | ARCHITECTURE.md §5 |
| 4. 质量 | 先写测试还是后写，最低覆盖率，类型检查，从不模拟什么 | CONTRIBUTING.md §5；如果不可协商，同时也是一条原则 |
| 5. 安全 | 身份验证、敏感数据、输入验证、法规合规 | ARCHITECTURE.md §10、SECURITY.md |
| 6. 流程 | 分支、约定式提交、合并或压缩、审批、PR 大小、允许的 AI 工具 | CONTRIBUTING.md §4、§6–7 |
| 7. 依赖 | 添加依赖的策略、禁止的库、构建还是购买 | 原则（如果不可协商）或 CONTRIBUTING.md |
| 8. 代理相关 | 命令（验证命令是必需的）、非显而易见的约定、关键或脆弱区域（棕地）、边界（总是/询问/从不） | AGENTS.md |
在第 8 轮中，验证命令是与其它技能（plan-to-tasks、implement、review）的契约。如果不存在，则建议 setup-guardrails-python（或语言对应的等效命令），或在 AGENTS.md 中保留为开放问题。如果项目将使用 review-prepush 或 review-pr，也提供可选的 ## Code review 部分（模板在 review-context/assets/AGENTS-code-review.md）：基础分支、高风险路径、报告语言……
3. 起草并写入
顺序：ARCHITECTURE.md → ADR → CONTRIBUTING.md → SECURITY.md → AGENTS.md。AGENTS.md 放在最后，因为它链接到所有其他文件。
- 从
assets/中的模板开始。删除目前尚不适用的部分；不要留空。 - ADR：将
ADR.md复制为docs/adr/0000-template.md（西班牙语中为0000-plantilla.md），将adr-README.md复制为docs/adr/README.md。为第 2-3 轮中的每个架构决策创建一个 ADR。棕地模式：只创建 3-5 个追溯性 ADR，针对最常被质疑的决策，并包括被舍弃的备选方案。 AGENTS.md必须包含：- “规划”行：在实施之前，对照
docs/ARCHITECTURE.md中的原则检查计划； - 指向
CONTRIBUTING.md的链接以了解流程。
- “规划”行：在实施之前，对照
CLAUDE.md仅包含@AGENTS.md，除非它已有其他内容。在这种情况下，建议将其内容移动到AGENTS.md中。pull_request_template.md放在.github/中。提供它，但不要强制使用。
4. 总结
列出创建或更改的文件以及遗留的开放问题。提醒用户：
AGENTS.md每月审查并精简，尤其是在更换模型时。ARCHITECTURE.md每个季度对照代码检查一次。- 代理重复的每个错误都会成为工具规则，或者作为最后的手段，成为“已知陷阱”下的一行。