：只靠对话编程，AI 很快会失控

AI 编码最麻烦的地方。不是它不会写代码，而是没有稳定的工程边界。它可能这次记得用 intl.get下次又硬编码中文；这次遵守组件拆分，下次把页面、状态、事件、样式全塞进一个 index.tsx；你让它修一个 bug，它顺手把旁边的代码风格也改了。

这些问题单独看都不严重，但会持续消耗 Code Review 的注意力。原本 Review 应该关注业务逻辑、交互边界、异常处理，结果变成了帮 AI 检查：有没有 any有没有中文硬编码、列表 key 用了 index、有没有乱改配置。

在我们的项目里遇到的问题：只停留在对话编程，没有强制机制。

Prompt 可以提醒 AI，但 Prompt 不是约束。README 可以写规范，但 AI 不一定每次都会读。我们真正需要的是一套工程化 Harness：在 AI 编辑代码的关键动作前插入检查点，把“建议”变成“机制”。

一句话概括这套程序：

说到原理速览。有 AI 规范驱动的差异

没有 Harness：AI 直接冲进代码库

没有 Harness 时AI 的工作流非常短：使用者提出需求，AI 直接编辑文件，接下来进入 Review。

sequenceDiagram
participant User as 开发者
participant AI as AI 编码助手
participant Repo as 代码仓库
participant Review as Code Review
User->AI: 实现一个 TODOLIST 页面
AI->Repo: 直接编辑 index.tsx
AI->Repo: 顺手补样式和状态逻辑
AI->Review: 提交结果
Review-->User: 发现 any、硬编码中文、key=index、组件过重
User->AI: 继续返工

这个流程的问题不是“AI 不聪明”，而是中间没有任何强制检查点。老实说，AI 是否读取规范、是否遵守 i18n、是否限制修改范围。完全依赖模型当时的上下文和运气。其实，

有 Harness：关键动作前先过闸

AgentFlow Web 的 Harness 基于 Claude Code Hooks 实现。主要是两个 Hook：

• PreToolUse: 在 AI 调用 Edit / Write 前执行
• PostToolUse: 在 AI 调用 Skill 后执行

sequenceDiagram
participant User as 开发者
participant AI as AI 编码助手
participant Hook as PreToolUse Hook
participant Skill as Skill 规范
participant State as Session State
participant Repo as 代码仓库
participant Snapshot as Snapshot / Audit
User->AI: 实现一个 TODOLIST 页面
AI->Hook: 请求编辑 .tsx 文件
Hook->Hook: 匹配文件规则
Hook->State: 检查 coding-standards 是否已加载
State-->Hook: 未加载
Hook-->AI: 阻断。提示先加载 coding-standards
AI->Skill: 加载 coding-standards
AI->Hook:
请求编辑
Hook->Snapshot: 保存原文件快照 + 写审计日志
Hook-->AI: 放行
AI->Repo: 编辑文件

This mechanism ensures that code changes are guided by project conventions before y even happen.

. AI 规范驱动工程设计

The harness is not a single script but a set of cooperating mechanisms.

. 先定义 AI 能在哪些地方动手

The goal is not to intercept every file. Test files,type declarations,third‑party dependencies,and harness files mselves should bypass checks. The first layer is an action space registry that applies strict constraints only to core business files.

// .claude/hooks/lib/match-rules.jsconst RULES = srcstore.*.ts$/i,skill:'coding-standards' },{ name:'API 层',pattern:/srcapi.*.ts$/i,skill:'coding-standards' },{ name:'自定义 Hook',pattern:/.*.ts$/i,skill:'coding-standards' },];

. 没有加载规范，不允许编辑

The second layer is a Skill Gate that checks wher current session has already loaded required skill . If not。editing is blocked.

// .claude/hooks/pre-edit-check.jsif ) {
audit({
session : sessionId,tool : toolName,file : filePath,rule : rule.name,skill : rule.skill,action : 'blocked',});// exit signal for Claude Code Hook – stderr will inform user what to load next.
process.stderr.write`);process.exit;}

. 防止 AI 陷入循环修改

A typical runaway mode is continuously editing a file until it diverges furr from its intended state. To mitigate this we impose execution boundaries based on edit counts per session and per file.

指标
当前值/阈值

// .claude/hooks/lib/session-state.jsconst DEFAULT_EDIT_LIMIT = /* e.g.,*/10;function incrementEditCount {
const state = loadState;state.editCount = + 1;saveState，不过，return state.editCount;}

. 让 AI 行为可追踪

Audit logs record every allow/deny decision and skill load event without capturing file contents. They help answer questions like “When did file start being edited?” and “Was an edit attempted before loading its required standards?”

{"ts":"2026-08-03T10::00Z","tool":"Edit","file":"src/pages/todo/index.tsx"。"action":"pass-skill-loaded"}

. 给 AI 修改加上回滚保险

The final layer saves a snapshot of a target file just before an allowed edit so that accidental destructive changes can be quickly rolled back locally.

// .claude/hooks/lib/snapshot.jsfunction saveSnapshot{
if ) return false;const content=fs.readFileSync;const snapshot={ts:new Date.toISOString。file:filePath,content};fs.writeFileSync);return true，}

. 实战迁移：实现一个 TODOLIST 页面

. 无 Harness：代码能跑，但 Review 压力转移给人

No-harness code often crams all logic into one component —business logic mixes with UI rendering and state handling in a single .tsx,leaving reviewers to catch issues like hard‑coded strings and unsafe keys.

. 有 Harness：先加载规范，再写代码

• A single attempt to edit an .tsx** triggers a pre‑edit hook that blocks until required skills are loaded.
• A prompt informs developers which skills y must call next .
• The resulting code naturally splits across multiple well‑named files . This includes separate types definitions。list components,item components,styling tokens—all governed by enforced conventions.
• Screenshots show that UI tokens replace hard‑coded colors and that all visible text goes through internationalization functions instead of raw Chinese literals.

. AI 规范驱动效果更好

/tbody/

指标	无 Harness	有 Harness	变化
文件数25+0?	无 Harness?19，?，?，?	有Harness？21，?	+?0，?

javascript// docs/harness-todolist-experiment/no-harness/index.tsxexport default function TodoPage{const =useState;const =useState;return}

`

---

---

结束演示

完成后效果

• 任何人都可以快速定位并复现问题
• 审核者不再需要从头检查所有细节
• 团队整体技术债务大幅下降

typescript// docs/harness-todolist-experiment/with-harness/types.tsexport interface TodoItem{id:string。title:string,completed:boolean}

typescript// docs/harness-todolist-experiment/with-harness/TodoList.tsxexport interface TodoListProps{items:Array,onToggle:=>void,onDelete:=>void}export default function TodoList{return}

typescript// docs/harness-todolist-experiment/with-harness/index.tsximport styles from './index.less';说起来，export default function TodoPage{const =useState;return}

---

结果对比

• 文件数量增加但职责更清晰
• 无“any”逃逸与不安全 key 使用
• 所有可见文本统一通过 intl.get 国际化处理
• 颜色与尺寸均使用 design token 而非硬编码常量

---

如何理解这些数据？

虽然带来了更多行数。但主要目标不是压缩代码，而是让后续维护成本降到最低。审核者可以把注意力放在业务体验和产品细节上，而非重复纠正基本编码违规。

---

团队落地路线图

1️⃣ 第一阶段 – 写清楚规范 - 创建 CLAUDE.md 与相应 Skill 文档 - 切勿立即启用阻断，只做语言统一

2️⃣ 第二阶段 – 针对关键文件启用阻断 - 从 .tsx,src/api,src/store。 src/hooks 开始 - 不要一开始就全仓库管控，以免干扰日常开发

3️⃣ 第三阶段 – 引入审计与回滚 - 当任务量增大后开启 audit log 与 snapshot 功能 - 为开发者提供快速恢复方法，让他们安心尝试

---

使用者痛点汇总

• - 审查员花费大量时间排除任何类型、安全 key 和硬编码文字问题。怎么说呢，

- 开发者担心每一次提交都被“技能门槛”阻挡导致效率低下。老实说，

- 团队缺乏可复现的标准流程。使得新成员难以快速上手或维护旧程序。

- 缺少本地快照导致错误修复后无法轻易回退到上一版本，引发多轮冲突与重复工作。

- 在多分支或多环境开发时“任意修改”导致合并冲突频繁出现，需要额外人工干预才可解决。

- 对于不熟悉国际化和设计程序的新成员经常出现硬编码文本或颜色值，被迫等候他人审核才能继续工作。

- 因为项目规模扩大。可读性差导致维护成本激增，需要工具帮助统一结构与风格才能保持长久可维护性。

---