0. 顶层整体视角（信息分层逻辑）

记住：一切的“源”是 spec.md（功能规格），其余文件均为衍生或支撑。

1. memory/ （项目“宪法与治理”）

1.1 memory/constitution.md

• What：项目的“开发宪法”——硬性基础原则集合（例如 Library-First、CLI 强制、Test-First、反过度抽象、集成优先测试等）。
• Why：
  • 统一 AI 与人类贡献者的系统级思维方式。
  • 防止在多迭代、多成员、多 AI 模型参与下偏离初衷。
  • 作为评审和拒绝“不符合项目精神”提交的依据。
• How：
  • 新特性规划前，让 AI / 人类都“读宪法”——可以在 prompt 中引用其核心条目。
  • 任何与宪法冲突的实现需显式记录 justification（理由），并在 PR 评审中讨论。
  • 更新宪法必须走变更流程（见 checklist）。

1.2 memory/constitution_update_checklist.md

• What：修改宪法时的审批清单（是否有破坏性影响、是否向后兼容、是否有记录等）。
• Why：防止随意变更原则导致“方法学漂移”或架构碎片化。
• How：
  • 修改前复制 checklist，填写变更标题、动机、影响面、回滚策略。
  • 评审通过后更新 constitution.md 并在 Git 历史中留存审议记录（建议提交信息含 “Constitution Update”）。

2. templates/ （模板驱动高质量生成）

2.1 templates/spec-template.md

• What：生成规范 spec.md 的骨架，包含功能描述、用户场景、功能需求、关键实体、测试与验收清单、[NEEDS CLARIFICATION] 标记策略等。
• Why：
  • 约束 AI 不要掺入“实现细节”
  • 强制显式列出不确定项，防止无声假设。
• How：
  • 不建议在此加入具体技术栈字段。
  • 自定义时：仅新增你团队“必填业务维度”（如合规、风控、国际化）。

2.2 templates/plan-template.md

• What：技术实施计划结构（架构视图、组件分解、数据流、接口契约指针、阶段 Gate、自查清单等）。
• Why：
  • 把 “WHAT” 转为 “HOW” 但又保持高层抽象→防止过早写代码。
  • 让 AI 先验证“结构是否健壮”，而不是直接跳入代码生成。
• How：
  • 若团队有特定“性能预算”“安全策略”，可在模板中预置栏目。
  • Phase -1 Gates（简化、反抽象、集成优先）要保留，防止膨胀。

2.3 templates/tasks-template.md

• What：任务拆分与并行标记（[P]）、依赖标识、交付标准格式。
• Why：
  • 保证任务粒度可执行、可估时、可追踪。
  • 避免纯自然语言“空洞任务”。
• How：
  • 可新增 “Owner”/“Estimate” 字段配合 PM 工具同步。
  • 任务变更时应反查是否需同步 plan/spec。

2.4 可能出现的其他模板（视版本而定）

• CLAUDE-template.md、research-template.md 等，用于统一 AI 行为或研究记录格式。

3. scripts/ （流程自动化与一致性保障）

扩展脚本时：保持“单一职责”，新增脚本需在 README 或内部开发手册中注册。

4. specs/-/ （特性级“单元宇宙”）

目录命名约定：

• NNN-kebab-name，数字递增（001、002……），slug 由初次描述自动生成。
• 建议：不要手动改编号；重命名 slug 要检查引用。

下面逐文件详解（按形成顺序和依赖关系组织）：

4.1 spec.md （功能规格）

• What：唯一的“业务与功能意图”根文件：包含范围、场景、功能需求（FR）、非功能约束（NFR）、关键实体与关系、测试/验收条件、风险与未决项。
• Why：所有后续 artefacts 必须可追溯映射到它（需求可追踪性矩阵思想）。
• How：
  • 填写或澄清 [NEEDS CLARIFICATION] 标记，最终需清零或解释保留原因。
  • 变更流程：每次修改应写进 commit message（如 “Spec: clarify FR-007 retention policy”）。
  • 可添加自定义区块：合规、数据治理、隐私策略。

4.2 plan.md （技术实施计划）

• What：抽象架构、模块划分、架构选型理由、数据流、组件边界、阶段 Gate、自查 checklist。
• Why：防止 AI 或成员直接从 spec “跃迁”到代码，遗漏架构合理性评估。
• How：
  • 每个技术决策要指向其 FR / NFR 来源（如 “Decision D3 -> FR-004, NFR-02”）。
  • 如果与宪法冲突，必须写 “Justification” 块。
  • 若后期发现实现困难，先回溯 plan 调整再改代码。

4.3 data-model.md （数据模型）

• What：实体 → 字段（类型/约束）→ 关系（1:N / M:N / 聚合）→ 语义说明。
• Why：统一 API / DB / 前端模型防止分歧；是合约与测试生成的一个核心源。
• How：
  • 优先用“概念模型”语言（领域话语）而非直接数据库表结构。
  • 变更字段需同步：contracts、测试、迁移脚本（如存在）。
  • 最好添加“来源需求（FR-xxx）”列以追溯。

4.4 contracts/

• What：接口协议（REST/OpenAPI/WebSocket 事件、CLI 命令列表、消息格式等）。
  • 示例：api-spec.json（OpenAPI）、signalr-spec.md、events.yml。
• Why：提供模块/客户端间“稳定契约”，支持自动生成 Stub/SDK/测试。
• How：
  • 不要在实现阶段随意改签名 → 若需修改，先改 spec 与 plan。
  • 建议为每个 endpoint/消息添加：来源 FR、成功/失败场景、错误码策略。

4.5 research.md

• What：围绕本功能的调研：框架对比、性能评估、风险分析、库版本锁定、参考资料链接。
• Why：让“决策理由”与“事实证据”绑定，避免经验化决策变成口口相传。
• How：
  • 结构建议：Question → Findings → Sources → Decision → Linked FR。
  • 添加日期戳（如 “2025-09-19 Research Refresh”）以提示过期风险。

4.6 quickstart.md

• What：最低摩擦的“运行/验证该功能”指南（启动命令、环境变量、最小测试路径）。
• Why：支持新成员快速加入；为 QA / 运维 / Demo 提供统一入口。
• How：
  • 只写“核心路径”，详尽部署放 README 或 ops 手册。
  • 可附：示例 CLI 调用 / cURL / seed 数据脚本指针。

4.7 tasks.md

• What：根据 plan+contracts+data-model 派生的任务拆解表。
• Why：组织执行、度量进度、控制并行化风险。
• How：
  • 任务命名建议：[Layer] Verb Object Qualifier（如 [Backend] Implement album reorder endpoint）。
  • 加 [P] 表示可并行；依赖用 “Blocked by #T5”。
  • 完成后若产生新需求 → 回写 spec（形成闭环）。

4.8 implementation-details/ （可能由后续命令或人工创建）

• What：存放深入技术说明，如复杂算法、性能调优策略、数据迁移流程、特定序列图等。
• Why：保持 plan.md / spec.md 高层“可阅读”，把噪音隔离。
• How：
  • 命名建议：caching-strategy.md, migration-plan-v1.md, rate-limiter-design.md。
  • 不要让这里“倒灌”成源码复制粘贴仓库；保持抽象层次。

4.9 可能派生的其他文件

5. 根目录常见文件

6. AI 协作类文件（如 CLAUDE.md）

• What：一个汇总性“AI 使用上下文”文件（当前约束、命令说明、历史决策摘要）。
• Why：为长周期对话提供“持久记忆”——在多轮交互中维持一致性。
• How：
  • 结构建议：Context / Active Features / Recent Decisions / Open Clarifications。
  • 可以让脚本（如 update-claude-md.sh）在每次新 feature 生成后自动补充摘要。

7. 文件之间的“溯源链路”（Traceability Map）

spec.md
  ├─ 派生 → plan.md
  │      ├─ 细化 → data-model.md
  │      ├─ 细化 → contracts/
  │      ├─ 触发 → research.md （补充信息反向修正 plan / spec）
  │      └─ 输出 → tasks.md
  │             └─ 驱动 → 代码 / 测试实现
  ├─ 校验 ← quickstart.md （验证路径来自 spec 用户旅程）
  └─ 指导 ← constitution.md（约束变更与架构风格）

任何一个下游文件的“重大变更”原则上必须向上溯源确认是否需要更新 spec / plan。

8. 协作与治理建议

9. 自定义扩展建议（成熟团队可引入）

10. 常见误区与纠偏

11. 示例：一个完整特性目录展开（带文件角色标注）

specs/
└── 003-chat-system/
    ├── spec.md                # 功能规格（源头）
    ├── plan.md                # 技术规划（结构与路径）
    ├── data-model.md          # 实体/关系模型
    ├── contracts/
    │   ├── api-spec.json      # REST/OpenAPI 合约
    │   └── websocket-events.md# 实时消息事件协议
    ├── research.md            # 库/协议对比与决策
    ├── quickstart.md          # 启动与最小验证
    ├── tasks.md               # 拆解任务（含并行标记）
    ├── implementation-details/
    │   ├── scaling-strategy.md
    │   └── message-retention-design.md
    └── attachments/           # （可选）图表/序列图/流程图

12. 快速判断“这个文件应不应该放这里”的三问法

1. 它是否属于“意图/需求解释”？→ spec.md
2. 是否是“需求到技术的翻译与结构化决策”？→ plan.md / research.md
3. 是否是“对外协议或内部协作契约”？→ contracts/
4. 是否是“数据语义中心”？→ data-model.md
5. 是否是“执行级拆解”？→ tasks.md
6. 是否是“具体实现策略/深度细节/调优”？→ implementation-details/
7. 是否跨特性且长期约束？→ memory/constitution.md
8. 是否是支撑型骨架？→ templates/
9. 是否是把流程自动化？→ scripts/

说明该内容混杂，需拆分

13. 维护节奏建议（周期化运营）

14. 你可以立刻落地的操作清单（Checklist）