AI 编程架构护栏

目标

帮助编程 Agent 在修改大型或复杂项目时，不破坏现有架构、核心功能或长期设计意图。

使用本 Skill 时，应将代码仓库视为事实的唯一来源，但应将人工维护的设计意图视为最高层级的指导原则。不要依赖冗长的对话历史获取关键上下文；关键规则必须记录在仓库文档中，或以可执行检查的形式落地。

核心模型

采用四层护栏模型：

1. 人类设计意图层  
2. Agent 同步的架构与验收文档层  
3. 硬性自动化约束层  
4. 人工评审与黄金规则反馈层

Agent 的任务并非自由即兴发挥，而是在清晰边界和反馈闭环内安全执行。

推荐的文档结构

为项目创建或完善护栏时，优先采用以下最小化结构：

AGENTS.md  
docs/DESIGN_INTENT.md  
docs/ARCHITECTURE.md  
docs/ACCEPTANCE_RULES.md  
docs/GOLDEN_RULES.md  
docs/ARCHITECTURE_DRIFT.md

DESIGN_INTENT.md 由人工维护，用于记录项目目标、核心架构原则、不可协商的技术权衡，以及关键历史设计决策。它是项目的“宪法”；切勿允许 Agent 用当前实现覆盖人类的设计意图。

ARCHITECTURE.md 记录当前已确认的架构图谱。Agent 可周期性地根据代码和 DESIGN_INTENT.md 同步该文档，但意外产生的架构偏移（drift）不得被自动合法化。

ACCEPTANCE_RULES.md 记录如何验证核心功能、架构承诺及非回归行为。

GOLDEN_RULES.md 记录从真实事故中提炼出的强约束规则。每条规则应包含：事故来源、禁止行为、必需行为，以及如何通过自动化方式强制执行。

ARCHITECTURE_DRIFT.md 记录设计意图与当前实现之间的差距，并按以下类别归类：符合设计意图、合理演进、技术债、需人工决策、违反设计。

开始编码前

在进行任何非平凡的代码变更前：

1. 若存在 AGENTS.md，请先阅读。
2. 若存在，依次阅读 docs/DESIGN_INTENT.md、docs/ARCHITECTURE.md、docs/ACCEPTANCE_RULES.md 和 docs/GOLDEN_RULES.md。
3. 明确本次变更不得破坏的架构边界与关键行为。
4. 编辑前，先陈述本次变更的范围。
5. 除非用户明确要求，否则不得主动执行大规模重构、重命名、迁移或抽象层全面改造。

若项目尚无护栏类文档，请先建立最小可行集；切勿一次性构建庞大的文档体系。

设计意图维护工作流

人类设计意图是最高锚点。更新 DESIGN_INTENT.md 时：

1. 保留历史决策内容；不得简单覆盖旧文本。
2. 新增设计意图时，须附带带日期的决策记录。
3. 不仅记录“发生了什么变化”，更要记录“为何如此变化”。
4. 保持篇幅简短，确保 Agent 能在编码前快速通读。
5. 禁止 Agent 以实现便利性替代人类设定的设计权衡。

推荐格式如下：

## YYYY-MM-DD - [决策标题]

设计意图：  
[系统必须保持或朝向演进的目标。]

依据：  
[该方向为何重要。]

影响：  
- [后续变更必须遵守的约束。]  
- [Agent 绝对不可破坏的内容。]

架构同步工作流

在某阶段工作完成后，或重大任务启动前，同步架构文档：

1. 通读 DESIGN_INTENT.md。
2. 检视相关代码。
3. 比对设计意图与当前代码实现。
4. 对每一处偏差进行分类：
   • aligned with intent
   • reasonable evolution
   • technical debt
   • needs human decision
   • violates design
5. 仅将已确认的架构内容写入 ARCHITECTURE.md。
6. 将未经确认或存疑的偏差写入 ARCHITECTURE_DRIFT.md。

切勿假设“当前代码即正确架构”。当前代码本身可能已坍塌或发生偏移。

架构验收测试

将架构承诺转化为可执行检查。针对每个架构基石（architectural cornerstone）：

1. 从 ARCHITECTURE.md 中识别关键节点。
2. 从代码中找出可观测的调用链、数据流或不变式，以证明该基石依然成立。
3. 编写聚焦的单元测试、集成测试、lint 规则或结构化检查。
4. 将检查项纳入常规验证流程（如 CI 流水线）。

示例：

架构基石：  
PlanAgent 必须维持多轮次持久化记忆。

可观测模式：  
连续完成 10 轮对话后，“检索—摘要/更新—持久化”流程必须在 memory-management 链中完整运行。

验收测试：  
模拟 10 轮对话；断言预期的 MemoryManager 方法被调用，且结果已写入持久化存储或上下文组装流程。

优先采用确定性检查，而非仅依赖 AI 判断：

类型检查 > 单元测试 > 积分测试 > 架构测试 > lint > CI > AI review > 提示提醒

AI review 仅为语义补充，不构成核心护栏。

硬性约束优先级

构建护栏时，应优先防止以下行为：

• 违反架构方向的跨层调用或导入
• 绕过核心服务、Repository、Memory Manager、Validator 或 Provider
• 为已有子系统引入竞争性重复实现
• 删除、削弱或规避回归测试
• 未同步更新验收规则即变更外部行为
• 用直接数据访问取代稳定抽象
• 无界复杂度、全局状态或隐式副作用

若项目具有清晰分层结构，应将允许的依赖方向编码为测试或 lint 规则。

黄金规则工作流

当现有护栏未能阻止架构坍塌、功能退化或架构偏移时：

1. 总结事故经过。
2. 分析为何现有文档或测试未能预防该问题。
3. 向 GOLDEN_RULES.md 新增一条规则。
4. 补充或提议一项确定性检查来强制执行该规则。
5. 将该规则关联至对应测试、lint、CI 检查或人工评审清单。

推荐格式如下：

## [规则标题]

事故来源：  
[发生了什么？何时发生？]

禁止行为：  
[Agent 再次不得执行的行为。]

必需行为：  
[符合架构规范的正确做法。]

执行方式：  
- [测试、lint、CI 检查或评审步骤。]

切勿将 GOLDEN_RULES.md 变为泛泛而谈的通用建议。应保持其简洁、高信噪比，并扎根于真实事故或高风险模式。

坍塌风险评审

Agent 完成一项有意义的变更后，在最终回复前，需核查以下问题：

1. 本次变更是否改变了架构边界？
2. 是否绕过了现有抽象？
3. 是否删除、削弱或规避了既有测试？
4. 是否更改了核心调用链？
5. 是否为已有子系统引入了竞争性实现？
6. 是否将职责错误地转移至不恰当模块？
7. 人工评审应首先聚焦哪些位置？

若任一问题答案提示存在风险，则需立即修复，或将其记录为需人工决策的架构偏移（architectural drift）。

输出预期

当用户要求设计护栏时，应交付：

• 需新增的最小文档集合
• 应编码为硬性约束的架构不变量（architectural invariants）
• 首批待实现的测试、lint 或结构化检查项
• 黄金规则反馈工作流
• 简明上线计划

当用户要求将护栏应用于代码时，应首先阅读现有文档与测试，实施小范围变更，并使用项目中最严格的自动化检查进行验证。