在面向文档驱动开发（DDD）模式下，我们摒弃传统的混乱投喂方式，采用 “双轨并行（Two-Track Parallel）” 架构。该架构明确了“全局规范”与“具体任务”的边界，确保 AI 既懂规矩（How），又懂需求（What）。

---

AI 辅助开发上下文架构指南 (Context Architecture Standard)

1. 核心架构：双轨并行模型

在向 AI 发起指令时，必须同时包含两条并行的上下文轨道。这两条轨道互不包含，但在生成代码时同时生效。

• 轨道 A（全局静态轨）： 定义项目的技术宪法（规范、风格、架构）。
• 轨道 B（局部动态轨）： 定义当前的任务工单（业务逻辑、功能需求）。
  

---

2. 轨道 A：全局规范 (Global Context)

此轨道负责建立项目的“长期记忆”和“行为准则”。为了避免冲突，请在以下两种方案中任选其一（二选一） 作为项目的单一真理来源。

方案一：Project Rules (IDE 托管配置)

• 定义：使用 Cursor/Windsurf 等 IDE 自带的 Project Rules 设置面板进行配置。
• 适用场景：适合个人开发者或不希望在代码仓库根目录增加额外配置文件的团队。
• 特点：隐性、跟随 IDE 配置漫游、配置简单。

方案二：AGENTS.md (文件化配置)

• 定义：在项目根目录创建 AGENTS.md 文件。
• 适用场景：适合团队协作，需要将“AI 规则”纳入 Git 版本控制（Version Control）的场景。
• 特点：显性、跟随代码仓库、便于 Code Review。

规范内容模板 (无论选哪种方案，内容应包含)：

角色设定：如 “Senior TypeScript Engineer”。技术栈约束：如 “Strictly use Next.js App Router”, “Tailwind CSS for styling”。代码风格：如 “Prefer functional components”, “Early returns”。工程路径：如 “Components go to /src/components, Libs go to /src/lib”。

---

3. 轨道 B：开发文档 (Local Task Context)

此轨道负责描述“当前要解决的具体问题”。它是动态的，随任务创建，随功能完成而归档。

• 载体：Markdown 文档 (推荐命名 docs/feature-xxx.md 或 specs/xxx_req.md)。
• 关系：它与轨道 A 是并行关系。不要在开发文档中重复轨道 A 里的技术栈定义（除非有特殊覆盖需求）。

文档编写标准 (The Spec)：

一个合格的开发文档应专注于 业务逻辑 与 数据流：

1. Goal (目标)：一句话描述这个功能做什么。
2. Schema (数据模型)：涉及的数据库表结构或 TypeScript 接口定义。
3. Flow (逻辑流程)：伪代码或步骤列表（Step 1… Step 2…）。
4. Edge Cases (边界情况)：报错、空状态、权限校验。

---

4. 协作工作流 (Workflow)

在实际开发中，通过组合两条轨道来驱动 AI：

步骤 1：确立轨道 A

• 检查项目根目录是否有 AGENTS.md，或者 检查 IDE 的 Project Rules 是否已配置。
• 注意：不要同时维护两者，以免造成规则冲突或维护负担。

步骤 2：编写轨道 B

• 为当前任务编写 docs/login_flow.md。

步骤 3：并行输入 (Prompting)

• 在对话框中，显式引用轨道 B，隐式（或自动）加载轨道 A。

标准 Prompt 范式：

“参考 {@docs/login_flow.md} 中的业务逻辑，请为我实现登录接口。请确保代码符合项目全局规则（{@AGENTS.md} 或 Project Rules）。”

---

5. 总结：两者的区别

维度	轨道 A：AGENTS.md / Project Rules	轨道 B：开发文档 (Specs)
选择逻辑	二选一 (Mutually Exclusive)	多份并存 (One per feature)
生命周期	长期有效，极少变动	短期有效，随任务迭代
关注点	形式 (Form)：代码风格、最佳实践	内容 (Content)：业务规则、用户需求
定位	公司的《员工手册》	具体的《任务工单》