Agent 效果 70% 靠 Harness？续篇：详述那些没讲透的细节实战

bboyzqh

288人浏览 · 2026-07-25 23:34:09

bboyzqh · 2026-07-25 23:34:09 发布

围绕着上篇《Agent 效果70%靠Harness？一文讲透如何构建可复用的 Harness 工程》讲一些实践过程中的细节，一家之言，欢迎讨论！

1. AGENTS.md、CLAUDE.md、MEMORY.md 分别记录什么？

AGENTS.md 定位是目录和导航文件，内容包括： openspec/specs/ 下的分域知识索引、活跃变更等。示例如下：

# AGENTS.md — 智能体导航

## 项目概述
MyProject 是一个 TypeScript 全栈应用，使用 React + Node.js。
所有代码由 Claude Code 生成，人类负责设计环境、明确意图、验证结果。

## 技术栈
- 语言: TypeScript (strict mode)
- 前端: React + Tailwind CSS
- 后端: Node.js + Express
- 测试: Vitest + Playwright
- 包管理: pnpm

## 规范系统
- 权威基准: openspec/specs/（当前系统行为的真实来源）
- 进行中变更: openspec/changes/（每个变更独立文件夹）
- 变更工作流: /opsx:propose → /opsx:apply → /opsx:archive

## 架构规则
- 分层依赖: Types → Config → Repo → Service → Runtime → UI
- 横切关注点通过 providers/ 统一入口
- 详细规则见 CLAUDE.md "架构约束" 章节

## 关键约束（详见 CLAUDE.md）
- 禁止未批准的第三方库
- 禁止 console.log（用结构化日志）
- 禁止 snapshot testing
- 所有外部数据在边界处验证（parse-don't-validate）

## 开发流程
1. /opsx:propose <change-name>   创建变更提案
2. 审查 proposal.md + design.md + tasks.md
3. /opsx:apply                   按 tasks.md 实现
4. /opsx:archive                  合并规范并归档

CLAUDE.md 承载项目级的规则，包括技术栈、命名约定、禁止和约束项等。示例如下：

# CLAUDE.md — 项目规则

## 架构约束

### 分层依赖模型
每个业务域内代码只能"向前"依赖固定层序：
Types → Config → Repo → Service → Runtime → UI

禁止反向依赖。禁止跨域直接引用（通过 Provider 接口交互）。

横切关注点（认证、遥测、功能标志）只能通过 src/providers/ 进入。

### 品味不变式
- 结构化日志：使用 src/shared/utils/logger.ts，禁止 console.log
- 文件大小限制：单文件不超过 300 行
- 命名约定：PascalCase 组件 / camelCase 函数 / SCREAMING_SNAKE 常量
- 所有 API 响应在边界处用 Zod 解析，禁止 YOLO 式探测数据
- 优先使用 src/shared/ 中的共享工具，禁止手写重复辅助函数

### 禁止项
- 禁止引入未批准的库：lodash, moment, date-fns, axios, styled-components
- 禁止 snapshot testing（用显式断言替代）
- 禁止 CSS-in-JS（仅用 Tailwind className）
- 禁止隐式 any 类型
- 禁止直接修改 openspec/specs/（必须通过 /opsx:propose 流程）

## 黄金原则（防漂移）
1. 复现代码库中已有模式前，先检查是否符合当前架构约束
2. 新增 API 端点必须先在 openspec/specs/ 中更新规范
3. 重复出现 3 次以上的逻辑必须提取到 src/shared/
4. 每个 PR 必须包含对应的 spec 更新或确认无需更新

## 错误修复指令
当 lint 报错时，按以下顺序处理：
- dependency-direction 违规 → 将依赖移至正确的层
- file-size 超限 → 拆分文件，保持单一职责
- unapproved-library → 使用 src/shared/ 中的替代方案
- console.log → 替换为 src/shared/utils/logger.ts 的结构化日志

MEMORY.md 承载演化状态（最近迁移、上周变更等）。示例：

# MEMORY.md — 项目演化状态

## 最近变更
- [2026-07-10] 认证系统从自研 JWT 迁移到 Clerk
  - 影响范围: src/auth/ 全部重写
  - 迁移原因: 自研方案维护成本高，Clerk 提供 2FA 开箱即用
  - 旧 JWT 代码已删除，不要参考 git 历史中的旧实现
  - 归档记录: openspec/changes/archive/2026-07-10-migrate-to-clerk-auth/

- [2026-07-01] 支付服务重构，拆分为 Order 和 Payment 两个子域
  - 原因: 单一 PaymentService 承担过多职责（500+ 行）
  - 新结构: payment/types.ts, payment/repo.ts, payment/service.ts
  - 归档记录: openspec/changes/archive/2026-07-01-refactor-payment-service/

## 活跃决策
- [待定] 通知系统是否从自建邮件切换到 SendGrid
  - 当前状态: proposal 已创建，design 待评审
  - 变更路径: openspec/changes/evaluate-sendgrid/

## 已知技术债务
- src/payment/ui/ 中有 2 个组件超过 300 行（计划本周 GC 任务拆分）
- openspec/specs/notification/ 缺少推送通知的验收场景

## 架构决策记录
- [2026-06-15] 选择 Zod 而非 yup 进行运行时验证
  - 原因: Zod 与 TypeScript 集成更好，类型推断更准确
- [2026-06-20] 选择 Tailwind 而非 styled-components
  - 原因: 消除 CSS-in-JS 运行时依赖，对智能体更可预测

2. 需求变更后怎么同步更新 AGENTS.md、MEMORY.md？

a. 更新时机：

当一次需求变更走完 propose → apply → sync → archive 后，要同步更新 AGENTS.md（仅当 spec 列表变化时，需要变更索引等）、更新 MEMORY.md

b. 怎么更新？

更新有两个方案，这里推荐两个方案结合起来使用：

方案一：在 .claude/skills/openspec-archive-change/SKILL.md 末尾追加一步：归档完成后，检查 openspec/specs/ 下是否新建了 spec、归档目录名，提示调用方更新 AGENTS.md 和 MEMORY.md。这是提示性步骤，不强制中断流程。
方案二：在 CLAUDE.md 的架构约束附近加一个「变更后文档同步检查清单」章节，这样无论是人还是 agent执行归档，都有可对照的清单。

两个方案结合下来的流程是：执行 opsx:archive -> 触发同步更新提醒（方案一）→ CLAUDE.md 提供操作手册（方案二）→ 执行更新 → 触发代码文档一致性检查 。形成「触发 → 指导 → 验证」闭环。

3. 文档代码一致性检查怎么做？什么时机做？

a. 怎么做？

文档代码一致性检查（比如校验“openspec/specs下规范内容”与“代码”一致性）实现有三种思路：

方案一：全量 Agent 审查方案。由 Agent 独立阅读需求规格说明（Specs）及代码实现进行校验。该方案灵活性最高，但存在 Token 消耗过大的成本问题。
方案二：纯代码规则校验方案。通过代码提取 Specs 规则并进行自动化比对。该方案执行效率高且完全由代码驱动，但在处理复杂逻辑时存在局限性。
方案三：混合架构方案（推荐）：采用“代码+Agent”的协同模式。将结构化、确定性的规则提取与比对交由代码高效完成，而将语义理解、复杂约束等模糊逻辑交由 Agent 处理，兼顾效率与准确性。

b. 触发时机

CLAUDE.md 中注意事项中配置示例：同步完成后可运行 bash openspec/scripts/check-spec-code-consistency.sh来验证
CI 流程可配置一致性检查阶段

注：需求 propose 阶段生成 tasks.md 时也可增加验证环节。

4. openspec/config.yaml 怎么定义？

openspec/config.yaml 是 OpenSpec 的‌项目级核心配置文件‌，主要是在运行 opsx:propose/apply 时，告诉AI如何生成提案/设计文档。包括用于定义默认工作流、注入项目上下文及技术规范，确保 AI 生成内容符合团队约定。‌‌

‌设定默认工作流‌：通过 schema 字段指定默认使用的规范模板（如 spec-driven 或自定义模式），避免每次命令重复参数。
注入项目语境‌：context 字段提供全局背景（技术栈、目录结构、编码惯例），AI 在生成任何工件时自动读取，防止“乱猜需求”。这里会和 CLAUDE.md 会有重复内容，需要遵守原则：

config.yaml 只放生成提案时需要了解的背景，而 CLAUDE.md 放开发者必须遵守的详细规范
约束生成规则‌：rules 字段针对特定产物（proposal/specs/design/tasks）设定强制性指令（如必须包含回滚计划、使用 Given/When/Then 格式），提升输出一致性。示例如下：

rules:
  proposal:
    - 提案需包含背景、目标、范围、成功标准
    - 技术变更需包含架构影响分析
  design:
    - 设计文档需包含架构图
    - 关键决策需说明原因
  tasks:
    - 任务拆分到可 2 小时完成
    - 每个任务需有验收标准
  spec:
    - 规范需包含输入、输出、异常处理
    - 接口变更需说明兼容性