ai-architecture-harness-en — AI架构整合英文版

AI 编码架构护栏目标 帮助编码代理修改大型或复杂项目而不破坏现有的架构、核心功能或长期设计意图。使用此 Skill 时，将仓库视为真实来源，但将人工维护的设计意图视为最高级别的指导。不要依赖长对话历史来获取关键上下文；关键规则必须在仓库文档或可执行检查中捕获。

核心模型 使用四层护栏模型：

• 人类设计意图层
• 代理同步架构和验收文档层
• 硬自动约束层
• 人类审查和黄金规则反馈层

推荐文档布局 创建或改进项目的护栏时，首选此最小结构： AGENTS.md docs/DESIGN_INTENT.md docs/ARCHITECTURE.md docs/ACCEPTANCE_RULES.md docs/GOLDEN_RULES.md docs/ARCHITECTURE_DRIFT.md DESIGN_INTENT.md 由人类维护，记录项目目标、核心架构原则、不可协商的权衡和历史设计决策。它是“宪法”；不要让代理用当前实现覆盖人类意图。 ARCHITECTURE.md 记录当前确认的架构图。它可能会定期由代理从代码和 DESIGN_INTENT.md 中同步，但意外的漂移不能被自动合法化。 ACCEPTANCE_RULES.md 记录如何验证核心功能、架构承诺和非回归行为。 GOLDEN_RULES.md 记录从实际事件中提炼出的强规则。每个规则应包括事件来源、禁止行为、所需行为和如何自动执行。 ARCHITECTURE_DRIFT.md 记录设计意图和当前实现之间的差距，分类为：与意图一致、合理演化、技术债务、需要人类决策或违反设计。

开始编码前 在进行任何非平凡的代码更改之前： 如果存在，阅读 AGENTS.md。 如果存在，阅读 docs/DESIGN_INTENT.md、docs/ARCHITECTURE.md、docs/ACCEPTANCE_RULES.md 和 docs/GOLDEN_RULES.md。 澄清此更改必须不破坏的架构边界和行为。 在编辑之前声明此更改的范围。 不要主动执行大型重构、重命名、迁移或抽象重构，除非用户明确要求。 如果项目尚无护栏文档，请首先创建一个最小可行集；不要一次性发明一个巨大的文档系统。

设计意图维护工作流 人类设计意图是顶级锚点。当更新 DESIGN_INTENT.md 时： 保留历史决策；不要简单地覆盖旧内容。 追加新意图，带有日期决策记录。 记录为什么发生了变化，而不仅仅是发生了什么变化。 保持足够短，以便代理在编码前可以阅读。 不要允许代理用实现便利性替换人类设计权衡。

推荐格式：

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

• [未来更改必须遵守的约束。]
• [代理必须不破坏的内容。]

架构同步工作流 在工作阶段完成或在开始重大任务之前，同步架构文档： 阅读 DESIGN_INTENT.md。 检查相关代码。 比较设计意图与当前代码。 将每个差距分类：与意图一致、合理演化、技术债务、需要人类决策或违反设计。 仅将确认的架构写入 ARCHITECTURE.md。 将未确认或可疑的差距写入 ARCHITECTURE_DRIFT.md。 不要假设“当前代码是正确的架构”。当前代码可能已经崩溃或漂移。

架构验收测试 将架构承诺转换为可执行的检查。对于每个架构基石： 从 ARCHITECTURE.md 中确定基石节点。 从代码中找到证明基石仍然成立的可观察的调用链、数据流或不变量。 编写专注的单元测试、集成测试、lint 规则或结构检查。 将检查添加到正常的验证工作流中。 示例： 架构基石：PlanAgent 必须维护多回合持久内存。 可观察模式：在 10 个连续的对话回合之后，检索、总结/更新并在内存管理链中持久化。 验收测试：模拟 10 个对话回合；断言预期的 MemoryManager 方法被调用并将结果输入持久性或上下文组装。

优先使用确定性检查而不是仅依赖 AI 判断： 类型检查 > 单元测试 > 集成测试 > 架构测试 > lint > CI > AI 审查 > 提示提醒 AI 审查仅作为语义补充，而不是核心护栏。

硬约束优先 在构建护栏时，优先防止： 违反架构方向的跨层调用或导入 绕过核心服务、存储库、内存管理器