ai-architecture-harness-zh

建立和使用 AI 编程架构护栏，防止架构坍缩、功能回退和长对话迭代漂移。Use when the user mentions AI 编程, Agent 编程, 架构坍缩, Harness Engineering, 设计意图, 验收规则, 黄金法则, 架构测试, 或希望让代码库更适合 AI Agent 安全修改。

AI 编程架构护栏

目标

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

使用本 Skill 时，把代码仓库视为事实来源，但把人工维护的设计意图视为最高层指导。不要依赖长对话历史保存关键上下文，关键规则必须沉淀到仓库文档或可执行检查中。

核心模型

使用四层护栏模型：

text

1. 人工设计意图层
2. Agent 同步的架构文档和验收文档层
3. 硬性自动化约束层
4. 人工巡检和黄金法则反馈层

Agent 的任务不是自由发挥，而是在明确边界和反馈回路中安全执行。

推荐文档结构

为项目创建或完善护栏时，优先使用这个最小结构：

text

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 阶段性同步，但不能把偶然漂移自动合法化。

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 用实现便利性替代人工设计取舍。

推荐格式：

markdown

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

设计意图：
[系统必须保持或演进成什么。]

原因：
[为什么这个方向重要。]

影响：
- [未来修改必须遵守的约束。]
- [Agent 不允许破坏的内容。]

架构同步流程

阶段性工作完成后，或重大任务开始前，同步架构文档：

1. 读取 DESIGN_INTENT.md。
2. 检查相关代码实现。
3. 对比设计意图和当前代码。
4. 对每个差异进行分类：
   • 符合意图
   • 合理演进
   • 技术债
   • 需要人工决策
   • 违反设计
5. 只把确认过的架构写入 ARCHITECTURE.md。
6. 把未确认或可疑差异写入 ARCHITECTURE_DRIFT.md。

不要默认“当前代码就是正确架构”。当前代码可能已经发生坍缩或漂移。

架构验收测试

把架构承诺转成可执行检查。对于每个架构基石：

1. 从 ARCHITECTURE.md 中识别架构基石节点。
2. 基于代码找出能证明该基石仍然有效的特殊调用链、数据流或不变量。
3. 编写聚焦的单元测试、集成测试、lint 规则或结构检查。
4. 把检查加入正常验证流程。

示例：

text

架构基石：
PlanAgent 必须具备多轮持续记忆。

可观测规律：
连续 10 轮对话后，必须触发记忆管理链路中的 retrieve、summarize/update、persist。

验收测试：
模拟 10 轮对话，断言预期的 MemoryManager 方法被调用，且结果进入持久化或上下文构建流程。

优先使用确定性检查，而不是只依赖 AI 判断：

text

类型检查 > 单元测试 > 集成测试 > 架构测试 > lint > CI > AI review > prompt 提醒

AI review 只能作为语义补充，不能作为核心护栏。

硬约束优先目标

构建护栏时，优先防止这些问题：

• 跨层调用或 import 违反架构方向
• 绕过核心 service、repository、memory manager、validator、provider
• 为已有子系统创建竞争性重复实现
• 删除、弱化或绕开回归测试
• 未更新验收规则就改变外部行为
• 用直接数据访问替代稳定抽象
• 引入无边界复杂度、全局状态或隐藏副作用

如果项目有清晰分层，应该把允许的依赖方向写成测试或 lint 规则。

黄金法则流程

当已有护栏没有挡住架构坍缩、功能回退或漂移时：

1. 总结事故。
2. 判断为什么现有文档或测试没有阻止它。
3. 在 GOLDEN_RULES.md 中新增规则。
4. 新增或提出一个确定性检查来执行该规则。
5. 把规则链接到测试、lint、CI 或 review checklist。

推荐格式：

markdown

## [规则标题]

事故来源：
[发生了什么，什么时候发生。]

禁止行为：
[Agent 不允许再做什么。]

必须行为：
[正确的架构行为是什么。]

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

不要把 GOLDEN_RULES.md 写成泛泛而谈的建议集合。它应该短、高信号，并来自真实事故或高风险模式。

坍缩风险审查

每次 Agent 完成有意义的修改后，最终答复前检查：

1. 本次是否修改了架构边界？
2. 是否绕过了已有抽象？
3. 是否删除、弱化或回避了已有测试？
4. 是否改变了核心调用链？
5. 是否为已有子系统创建了竞争性实现？
6. 是否把职责移动到了错误模块？
7. 人工 review 应该优先看哪里？

如果答案中存在风险，要么修复，要么记录为需要人工决策的架构漂移。

输出方式

当用户要求设计护栏时，输出：

• 最小需要新增的文档集合
• 应该编码成硬约束的架构不变量
• 第一批应该实现的测试、lint 或结构检查
• 黄金法则反馈流程
• 简短落地计划

当用户要求把护栏应用到代码时，先阅读已有文档和测试，再小范围修改，并使用当前项目最强的自动化检查完成验证