一、 设计哲学与核心机制
在 AI 辅助或 AI 主导（AI-Driven）的中大型单一项目开发中，核心工程逻辑是：“机器可验证的契约约束 + 层次化提示词 + 自动化门禁”。
1. 核心解决痛点
长期与 AI 深度结对编码中，最大的工程挑战在于 “熵增与上下文漂移”：
- 遗忘既有契约：在修改某模块时，悄悄打破原有架构分层或依赖约定；
- 发散与重复造轮子：项目中已有通用工具与抽象，AI 因上下文未命中而重复实现；
- 全量测试风暴：修改微小改动后盲目拉起耗时数十分钟的全局全量构建与 E2E 测试，导致 Token 与时间严重浪费。
本规划模板旨在通过工程化确定性约束 AI 的不确定性，建立稳定可靠的自治协作护栏。
2. 治理根基与多客户端接入垫片（Adapters）
在工程根目录中，采用 “多客户端接入垫片 + 单一事实源（Single Source of Truth）” 的适配模式：
| 目录 | 适用生态 / 客户端 | 作用与机制 |
|---|---|---|
.agents/ | Google Antigravity (AGY) | 官方工作区定制规范目录，也是全项目的唯一架构权威与治理基准。 |
.claude/ | Claude Code CLI (Anthropic) | 适配 Claude Code 约定的配置结构，内含 commands/（注册快捷指令）与 skills/。 |
.codex/ | OpenAI Codex CLI / 生态 | 适配 Codex CLI 约定的 prompts/ 与 skills/ 路径。 |
.agent/ | Cursor / Windsurf / OpenSpec | 兼容风行类 Agent 与 OpenSpec 工作流标准，内含 workflows/ 与 skills/。 |
设计动机：各 AI 工具尚未形成统一的规范路径。通过将核心架构规则收敛在根目录
AGENTS.md与.agents/notes/，其他目录仅做轻量符号链接或命令映射，既抹平了团队成员的工具差异，又确保了唯一权威源。
二、 适用性评估与分水岭
本模板方案并非银弹，适用于具备一定复杂度与生命周期的系统：
1. 强契合场景（ROI 显著）
- 长生命周期项目：维护周期数月或数年，需要依赖
notes/（ADR）作为跨会话的“项目外脑”，避免 AI 忘记历史设计决策； - 物理架构分层严格：如桌面端（主进程/渲染进程）、前后端同构、跨端跨语言（如 Swift + C++ 底层），极需依赖静态门禁阻止跨层越界；
- AI 编码深度结对：AI 编写代码比例 > 70%，人类主导架构 Review 与决策把控。
2. 不适用场景（负担大于收益）
- POC / 原型验证 / 黑客松：需求频繁推翻，生命周期极短，维护 ADR 与门禁开销过大；
- 单体小脚本 / 轻量工具库：逻辑内聚在少数文件内，AI 上下文窗口可完整覆盖，无漂移风险；
- 纯静态展示站：无复杂领域逻辑与信任边界。
三、 单一项目推荐目录骨架
plaintext
my-single-project/
├── AGENTS.md # 【顶层公理】开发哲学、环境、全局安全红线、测试基准
├── docs/
│ ├── AGENTS.md # 文档规范与编写要求
│ ├── architecture.md # 物理架构与模块依赖拓扑
│ ├── development.md # 本地环境与核心脚本指引
│ └── testing.md # 验证策略与推荐执行命令
├── src/
│ ├── modules/
│ │ └── AGENTS.md # 业务模块专属约束（禁止跨层乱引）
│ └── shared/
│ └── AGENTS.md # 共享基础库约束（严禁反向依赖业务层）
├── .agents/ # 核心治理基准目录 (Antigravity / 治理权威)
│ ├── notes/ # 架构决策记录 (ADR)
│ │ ├── README.md # Note 书写规范与状态生命周期说明
│ │ ├── proposed/ # 提案中（未实现）
│ │ ├── implemented/ # 已合入基线
│ │ └── rejected/ # 已否决方案（防止 AI 重蹈覆辙）
│ └── skills/ # 项目专属轻量技能
│ └── project-validate-change/ # 引导 AI 执行最小验证集的 Skill
│ └── SKILL.md
├── .claude/ # (可选) Claude Code 接入层 (commands/ 等)
├── .agent/ # (可选) Cursor / OpenSpec 工作流 (workflows/ 等)
└── scripts/
├── check-agent-contracts.mjs # 自动化检查 Agent 规则文档合规性
└── check-boundaries.mjs # 物理架构依赖边界静态校验四、 四大核心落地要点
1. 指令分层收敛，杜绝单文件膨胀（Hierarchical Rules）
- 根目录
AGENTS.md精炼化：建议控制在 150 ~ 200 行以内，只立最硬性的“项目公理”（语言版本、包管理器、环境安全、全局提交规范）； - 子目录就近所有权（Local Context）：在
src/modules/AGENTS.md约束业务领域逻辑，在src/shared/AGENTS.md约束共享层无状态性。AI 仅在访问对应子目录时加载局部上下文，兼顾 Token 节约与高遵循度。
2. 用“架构决策（Agent Notes）”锁定不可逆修改
- 不可逆边界：涉及数据库 Schema、公开 API 契约、鉴权机制、核心目录解构的改动，强制要求 AI 先编写或更新
.agents/notes/，否则不允许直接落地代码； - 状态三态流转：
proposed/：方案设计中，供人类 Review；implemented/：变更已合入，作为项目事实标准；rejected/：明确否决的方案，附带否决理由，阻止后续 AI 重复提出相同缺陷方案。
3. 脚本化门禁：用代码约束 AI（Guardrails as Code）
- 将规则校验集成进 CI 或本地快速命令（如
npm run check:governance）：- 检查关键
AGENTS.md是否缺失或物理行数超标； - 静态分析依赖边界（如利用
dependency-cruiser或 ESLint 规则），确保上层模块无法被底层反向导入； - 阻止非法文件修改（如直接改动锁文件或核心协议）。
- 检查关键
4. 专属“轻量验证技能”（Minimum Verification Skill）
- 为项目量身定制专用 Skill（如
project-validate-change）：- 能够根据改动的文件路径（Path-to-Test Mapping），精准指示 AI 只运行关联的单元测试；
- 明确豁免非代码纯文本（Markdown、配置说明等）的构建与测试，彻底杜绝测试风暴。
五、 渐进式演进路线
无需在起步阶段一次性落地全部复杂度，推荐按项目成熟度分级推进：
plaintext
【L1 轻量级（起步探索期）】
└── 仅保留根目录 AGENTS.md（百行以内，仅立语言版本、目录边界、禁止越权操作）
【L2 标准级（平稳开发/功能扩展期）】
├── 根目录 AGENTS.md + 模块级子 AGENTS.md（就近加载）
└── 1~2 个专属 Skills（如最小化精准测试执行引导）
【L3 严谨级（长期维护/核心商业项目）】
├── 继承 L2 全部能力
├── .agents/notes/（完整的 proposed / implemented / rejected ADR 生命周期体系）
└── scripts/ 自动化治理门禁（契约合规静态扫描、依赖拓扑校验）