ClawHub

ai-architecture-harness-zh

Other

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

Install

openclaw skills install ai-architecture-harness-zh

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

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. 对每个差异进行分类：
    • 符合意图
    • 合理演进
    • 技术债
    • 需要人工决策
    • 违反设计
  5. 只把确认过的架构写入 ARCHITECTURE.md。
  6. 把未确认或可疑差异写入 ARCHITECTURE_DRIFT.md。

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

架构验收测试

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

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

示例：

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

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

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

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

类型检查 > 单元测试 > 集成测试 > 架构测试 > 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。

推荐格式：

## [规则标题]

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

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

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

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

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

坍缩风险审查

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

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

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

输出方式

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

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

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