Harness Engineering被广泛视为一种新兴的软件开发范式，正在重新定义软件开发的本质。未来的软件开发正朝端到端（E2E）的方向加速演进，软件生命周期内的生产效率与协同效率都将经历根本性的重塑。未来，软件工程内的各种角色（产品、设计、PM、前后端、测试、运维）都将被模糊化，可能就是 变成 AI开发人员*1 + Harness Engineering 就搞定了，再也不会有 后端写接口前端对接的这种环节了，只有提出需求 -> 验收需求 直接到端交付的环境，过程就是AI全做了，有可能那些一连串的软件工程角色都是变成一个个SubAgent了。

引言

前段时间小马也介绍了瞬间火爆的 Harness Engineering 概念《Harness Engineering：从“调教”到“驾驭”AI的革命性实践》，然而，纸上得来终觉浅，空谈终究不是办法，最终还是要实践的。那么面对如此抽象的一个词或者概念，具体应该如何落地呢？小马今天就是来聊实践落地的。

小马在最近的一段时间刚好着手实践了一个项目，基于AI 编程IDE Codebuddy 实现的真实业务项目 Harness Engineering，已经简单跑通了所有 Harness Engineering 要素环节，具备了 Harness Engineering 思想的架构。我们接下来来逐一探讨如何实现一个新项目或者老项目的 驾驭工程环境。

第一章：什么是 Harness Engineering

1.1 定义

Harness Engineering 是一种面向 AI 辅助软件开发的方法论，通过构建「约束系统 + 技能系统 + 工作流系统」，让 AI 在既定轨道上高效、稳定地产出符合预期的代码。

「Harness」原指「马具/挽具」，在工程领域引申为「约束装置」——不是限制能力，而是让能力在可控范围内发挥最大效用。

1.2 核心思想

传统开发: 人 → 代码 → 质量
Harness Engineering: 人 → [规则 + 技能 + 工作流] → AI → 代码 → 质量

通过这三层系统，将人类的工程经验、领域知识、质量标准编码化，让 AI 在每一次交互中自动遵循，而不是每次都依赖人类提醒。

1.3 与传统开发模式的区别

维度	传统开发	Harness Engineering
AI 行为	依赖 Prompt 随机发挥	通过规则固化约束
知识传递	每次会话重新描述	技能包持久化
流程控制	口头提醒或靠自觉	工作流强制执行
质量保证	人工 Code Review	自动化验收 + 审计

---

第二章：Harness Engineering 的核心要素

2.1 要素总览

一个完整的 Harness Engineering 系统包含 6 大要素：

┌─────────────────────────────────────────────────────────────┐
│                     Harness Engineering                      │
├─────────────────────────────────────────────────────────────┤
│  ┌───────────┐  ┌───────────┐  ┌───────────┐               │
│  │   Rules   │  │  Skills   │  │ Workflows │   ← 控制层    │
│  │  规则约束  │  │ 技能包    │  │ 工作流    │               │
│  └─────┬─────┘  └─────┬─────┘  └─────┬─────┘               │
│  ┌─────┴─────┐  ┌─────┴─────┐  ┌─────┴─────┐               │
│  │  Agents   │  │   Hooks   │  │ Observ.   │   ← 执行层    │
│  │ 子Agent   │  │ 生命周期钩 │  │ 可观测性  │               │
│  └───────────┘  └───────────┘  └───────────┘               │
└─────────────────────────────────────────────────────────────┘

2.2 要素一：规则约束（Rules）

定义：对 AI 行为进行结构化约束的声明式文档。

作用：

• 将工程规范编码化，让 AI 自动遵循
• 区分「始终生效」和「按需加载」规则
• 通过优先级（P0-P5）解决规则冲突

设计原则：

1. 单一职责：每条规则只解决一个问题
2. 明确触发：规则应清晰说明在什么场景下触发
3. 可验证：规则应有明确的验收标准
4. 分层级：P0 必须遵守，P5 指导建议

规则结构示例：

---
alwaysApply: true  # 是否始终生效
---

# 规则名称

## 触发场景
[何时应该触发这条规则]

## 具体要求
[应该怎么做]

## 禁止行为
[不应该做什么]

2.3 要素二：技能包（Skills）

定义：封装特定领域知识、模板和标准流程的可复用包。

作用：

• 将领域专家经验固化为可调用的模板
• 避免每次从零开始描述项目规范
• 通过版本管理追踪知识演进

技能包结构：

skill-name/
├── SKILL.md           # 定义 + 版本号（SemVer）
├── CHANGELOG.md       # 变更日志
├── templates/         # 代码模板
└── docs/              # 领域知识文档

设计原则：

1. 版本化：采用 SemVer，每次变更记录 CHANGELOG
2. 场景化：一个技能包解决一类问题
3. 可组合：多个技能包可叠加使用
4. 分层级：项目级技能（团队共享）vs 用户级技能（个人）

2.4 要素三：结构化工作流（Workflows）

定义：将复杂任务拆解为可验证的阶段序列。

作用：

• 确保每次变更都经过完整的质量门禁
• 通过阶段性「Gate」防止带病代码进入下一阶段
• 提供清晰的进度可视化和状态管理

工作流设计原则：

1. 阶段化：拆分大任务为多个可独立验证的小任务
2. 可回退：每个阶段有明确的验收标准，不通过则回退
3. 强制确认：关键阶段必须人类确认才能继续
4. 持久化：每个阶段产出物（文档/代码）持久化存储

典型工作流示例：

Propose（提案）→ Review（评审）→ Apply（实施）→ Verify（验证）→ Archive（归档）
     ↑              ↑              ↑              ↑              ↑
   产出设计        产出评审        产出代码       产出验证       产出归档
   必须确认        必须通过        必须测试       必须部署       必须提交

2.5 要素四：子 Agent（Agents）

定义：专门化的小型 AI，负责特定领域的自动化任务。

作用：

• 将通用 AI 变成领域专家
• 并行处理多个专项任务
• 通过专一职责保证输出质量

设计原则：

1. 专一性：每个 Agent 只做一个领域的任务
2. 可调用：通过标准化接口触发
3. 有边界：明确 Agent 能做什么、不能做什么
4. 可扩展：通过配置新增 Agent 类型

2.6 要素五：生命周期钩子（Hooks）

定义：在 AI 执行操作的关键节点确定性执行的脚本。

作用：

• 将「应该做」变成「必须做」
• 提供强制性的质量门禁
• 记录操作日志用于审计

与 Rules 的区别：

维度	Rules（规则）	Hooks（钩子）
执行方式	依赖 AI 自觉遵守	系统强制执行
约束力	软约束	硬约束
失败处理	提示警告	阻止继续
适用场景	流程/行为约束	安全/质量强制

设计原则：

1. 轻量化：Hook 应快速执行，不阻塞交互
2. 幂等性：重复执行结果一致
3. 可观测：Hook 执行结果记录日志
4. 可配置：通过配置文件启用/禁用特定 Hook

2.7 要素六：可观测性与治理（Observability）

定义：对 AI 协作过程进行全面监控、审计和分析的系统。

作用：

• 量化 AI 协作效率和质量
• 识别高频违规模式并针对性改进
• 为规则迭代提供数据支撑

可观测性维度：

维度	内容	产出
性能监控	Hook 耗时、AI 响应时间	性能趋势报告
质量监控	测试通过率、验收成功率	质量仪表盘
违规审计	拦截事件、违规模式	违规统计报告
规则依赖	规则间依赖关系	依赖关系图

设计原则：

1. 结构化日志：统一 JSON 格式，便于解析分析
2. 分层存储：运行时日志 vs 违规日志分离
3. 可视化：提供仪表盘直观展示数据
4. 闭环反馈：发现异常 → 改进规则 → 验证效果

---

第三章：为什么要用 Harness Engineering

3.1 解决的核心问题

问题一：AI 行为不可预测

症状：AI 输出的代码风格不一致、违反项目规范、出现安全风险。

原因：没有明确的约束体系，AI 依靠「常识」自由发挥。

Harness 解决方案：通过 Rules + Hooks 构建双保险，Rules 软约束 + Hooks 硬执行，确保 AI 行为可预期。

问题二：知识无法复用

症状：每次新会话都要重新解释项目规范，同样的错误反复出现。

原因：依赖人类在每次对话中重复传递知识。

Harness 解决方案：通过 Skills 将领域知识封装为可复用包，新会话直接加载即可。

问题三：流程缺乏控制

症状：代码写完直接提交，测试靠人工，部署靠运气。

原因：没有结构化的工作流，每个阶段没有明确的产出物和验收标准。

Harness 解决方案：通过 Workflows 定义阶段序列和 Gate，确保每个阶段都经过验证。

问题四：问题发现滞后

症状：代码部署后发现问题，修复成本高。

原因：缺乏运行时监控和提前验收机制。

Harness 解决方案：通过 Hooks + Observability 实现「左移」验证，在代码编写阶段发现问题。

3.2 适用场景

Harness Engineering 特别适合以下场景：

场景	说明
业务代码开发	需要遵循规范、分层架构的项目
多人协作	需要统一开发标准、避免个人风格差异
高质量要求	对安全性、稳定性有严格要求的系统
AI 深度参与	AI 承担主要编码工作的项目

3.3 投入产出比

投入:
├── 初期建设：构建 Rules/Skills/Hooks（一次性）
├── 持续维护：规则迭代、知识更新（少量）
└── 治理建设：日志分析、仪表盘（少量）

产出:
├── AI 行为可预期（降低返工）
├── 质量门禁自动化（减少人工检查）
├── 知识复用（减少重复解释）
└── 问题早期发现（降低修复成本）

---

第四章：通用实践方法论

严格意义上来讲，这章才是本文的重点部分。这里是根据小马当前的项目来总结出的通用的实践方法论，亲测有效，目录如下：

如果说你非要一个官方的范式来参考，可以阅读 OpenAI 的官方文档。

4.1 方法论框架

┌─────────────────────────────────────────────────────────────────┐
│                    Harness Engineering 方法论                   │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  第一步：建立控制层                                             │
│  ├── 定义规则体系（Rules）                                      │
│  ├── 构建技能包（Skills）                                       │
│  └── 设计工作流（Workflows）                                    │
│                                                                  │
│  第二步：建立执行层                                             │
│  ├── 部署生命周期钩子（Hooks）                                  │
│  ├── 配置子 Agent（Agents）                                      │
│  └── 集成外部工具（Integrations）                                │
│                                                                  │
│  第三步：建立观测层                                             │
│  ├── 实施监控日志（Monitor）                                     │
│  ├── 建立违规审计（Audit）                                      │
│  └── 构建可视化仪表盘（Dashboard）                               │
│                                                                  │
│  第四步：持续迭代                                               │
│  ├── 问题闭环（教训 → 规则）                                    │
│  ├── 规则依赖管理（依赖关系图）                                  │
│  └── 规则优先级维护（冲突检测）                                  │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

4.2 第一步：建立控制层

4.2.1 定义规则体系

步骤一：识别约束点

分析项目中 AI 常犯的错误，识别需要约束的行为：

约束类型	示例	约束方式
安全约束	禁止修改 vendor/、.git/	Hook 硬拦截
流程约束	业务代码修改必须走流程	Rule 软约束
质量约束	必须编写单元测试	Rule 软约束
行为约束	Windows 环境禁止 Linux 语法	Rule 软约束

步骤二：编写规则文档

每条规则应包含：

• 元数据：alwaysApply、description
• 触发场景：何时应该遵守这条规则
• 具体要求：应该怎么做
• 禁止行为：不应该做什么
• 验证方式：如何确认规则被执行

步骤三：建立规则优先级

当规则冲突时，高优先级规则优先：

优先级	类别	说明
P0	安全硬约束	Hooks 强制，不可违反
P1	安全软约束	凭证/数据安全
P2	流程约束	工作流程控制
P3	质量约束	测试/部署质量
P4	行为约束	AI 行为偏好
P5	领域指导	开发技能/命名

步骤四：维护规则依赖图

确保规则之间无矛盾：

## 依赖关系示例

| 规则 A（依赖方） | 规则 B（被依赖方） | 说明 |
|------------------|-------------------|------|
| auto-deploy      | auto-testing      | 必须先有测试结果才能决定是否部署 |
| deploy-verify    | anydev            | 部署验证需要通过远程环境 |

4.2.2 构建技能包

步骤一：识别技能领域

分析项目涉及的技术栈和业务领域：

领域	示例	包含内容
领域技能	游戏活动后端、电商系统	代码模板、建表语句、配置格式
流程技能	OpenSpec 工作流	提案、实施、归档流程
工具技能	环境检查、测试运行	自动化脚本、命令封装

步骤二：设计技能包结构

skill-name/
├── SKILL.md           # 技能定义、版本号、使用说明
├── CHANGELOG.md       # 变更历史（SemVer 格式）
├── templates/         # 代码模板
│   ├── controller.php
│   ├── dao.php
│   └── service.php
└── docs/              # 领域知识文档
    ├── 分表规范.md
    └── 奖励配置.md

步骤三：定义版本规范

采用 SemVer：

• 主版本（Major）：不兼容的重大变更
• 次版本（Minor）：向后兼容的功能新增
• 补丁（Patch）：向后兼容的问题修复

步骤四：编写 SKILL.md

# {技能名称} v{Major.Minor.Patch}

## 简介
{一句话描述技能用途}

## 触发场景
{何时应该使用这个技能}

## 使用方法
{如何使用这个技能}

## 包含内容
{技能包含的模板/知识}

## 注意事项
{使用时需要注意的事项}

4.2.3 设计工作流

步骤一：定义阶段序列

将完整开发周期拆分为多个阶段：

Stage 1: Propose（提案）
    ↓ [产出：proposal + design + tasks]
Stage 2: Apply（实施）
    ↓ [产出：代码 + 测试]
Stage 3: Verify（验证）
    ↓ [产出：部署验证报告]
Stage 4: Archive（归档）
    ↓ [产出：归档文档]

步骤二：定义 Gate 标准

每个阶段之间设置 Gate，只有满足标准才能进入下一阶段：

Gate	验收标准	失败处理
Propose → Apply	人类确认提案	等待确认
Apply → Verify	单元测试全部通过	阻塞，直到修复
Verify → Archive	部署验证通过	报告失败，等指示
Archive → 提交	归档完成	提示用户提交

步骤三：定义产出物格式

每个阶段应产出可验证的文档：

阶段	产出物	说明
Propose	proposal.md, design.md, tasks.md	变更方案文档
Apply	代码文件、测试文件	可执行的代码
Verify	测试报告、部署验证报告	验证结果记录
Archive	归档说明、规格同步	完成状态记录

步骤四：设计确认机制

关键阶段必须人类确认才能继续：

## 2. Propose 完成后必须等待确认

Propose 阶段完成后，**必须停下来**向用户展示提案摘要，
并等待用户明确确认后才能进入 Apply 阶段。

### 禁止行为
❌ Propose 完成后直接进入 Apply 修改代码
❌ 把"用户发起了请求"等同于"用户确认了提案"

4.3 第二步：建立执行层

4.3.1 部署生命周期钩子

步骤一：识别 Hook 点

在 AI 执行的关键节点插入 Hook：

事件	Hook 类型	用途
写入文件前	PreToolUse	阻止危险操作、保护敏感路径
写入文件后	PostToolUse	语法检查、质量验证
执行命令后	PostToolUse	结果检查、日志记录

步骤二：设计 Hook 脚本

# file-protect.py 示例
import sys
import re

PROTECTED_PATTERNS = [
    'vendor/',
    '.git/',
    '.env',
    'node_modules/'
]

def main():
    file_path = sys.argv[1] if len(sys.argv) > 1 else ''
    
    for pattern in PROTECTED_PATTERNS:
        if pattern in file_path:
            print(f"[file-protect] Blocked: {file_path} matches pattern '{pattern}'")
            sys.exit(2)  # 阻止继续
    
    sys.exit(0)  # 放行

if __name__ == '__main__':
    main()

步骤三：配置 Hook 触发

通过 settings.json 配置 Hook：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "python .codebuddy/hooks/file-protect.py {filePath}"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "python .codebuddy/hooks/php-lint.py {filePath}"
          }
        ]
      }
    ]
  }
}

步骤四：Hook 日志集成

Hook 应自动记录执行日志：

{
  "ts": "2026-05-09T14:00:00",
  "event": "hook_exec",
  "source": "php-lint",
  "target": "controller/Foo.php",
  "duration_ms": 120,
  "result": "pass"
}

4.3.2 配置子 Agent

步骤一：识别专项任务

分析项目中需要专项 AI 处理的任务：

任务类型	示例	Agent 职责
代码审查	领奖流程、Dao 规范	检查安全性、规范性
测试生成	单元测试、集成测试	生成测试用例
文档生成	API 文档、变更记录	产出结构化文档

步骤二：定义 Agent 能力边界

每个 Agent 应有清晰的职责说明：

## Agent: code-reviewer

### 职责
- 检查领奖流程是否符合安全规范
- 验证 Dao 层分表逻辑是否正确
- 检查命名约定是否统一
- 识别潜在的安全风险

### 触发方式
完成代码编写后请求"代码审查"或"review"

### 输出格式
结构化审查报告，包含问题列表和改进建议

步骤三：Agent 间通信设计（如需多 Agent 协作）

graph LR
    A[主 Agent] -->|任务分发| B[code-reviewer]
    A -->|任务分发| C[test-generator]
    B -->|审查结果| A
    C -->|测试用例| A

4.3.3 集成外部工具

步骤一：识别集成点

外部工具	集成方式	用途
远程环境	AnyDev / SSH	部署验证
CI/CD	Webhook	自动化测试
消息通知	企业微信	状态通知
版本控制	Git	代码管理

步骤二：设计配置管理

{
  "integrations": {
    "anydev": {
      "defaultEnvironment": "k3-swoole",
      "container": "k3-swoole",
      "port": 10601
    },
    "wecom": {
      "enabled": true,
      "webhook": "https://wecom.example.com/..."
    }
  }
}

4.4 第三步：建立观测层

4.4.1 实施监控日志

步骤一：定义日志格式

统一 JSON 格式，便于解析：

{
  "ts": "2026-05-09T14:00:00",
  "event": "hook_exec",
  "source": "php-lint",
  "target": "controller/Foo.php",
  "duration_ms": 120,
  "result": "pass|block|syntax_error"
}

步骤二：定义监控维度

维度	内容	指标
Hook 耗时	每次 Hook 执行时间	avg, p95, max
测试执行	单元测试运行时间	pass/fail, duration
部署验证	上传 → 验证时间	total_duration
工作流阶段	各阶段耗时	propose/apply/verify/archive

步骤三：日志存储策略

日志类型	保留时间	存储位置
运行时监控	30 天	.codebuddy/logs/monitor-*.log
违规审计	90 天	.codebuddy/logs/violations/*.jsonl

4.4.2 建立违规审计

步骤一：记录违规事件

{
  "ts": "2026-05-09T14:00:00",
  "hook": "file-protect",
  "action": "blocked",
  "target": "vendor/autoload.php",
  "pattern_matched": "vendor/",
  "context": "AI 尝试修改 vendor 下的文件"
}

步骤二：生成统计报告

# 约束违规统计报告

更新时间: 2026-05-10

## 总览

| 指标 | 数值 |
|------|------|
| 总拦截次数 | 12 |
| file-protect 拦截 | 8 |
| php-lint 失败 | 4 |

## 高频违规模式 (Top 5)

| 排名 | 模式 | 次数 | 建议 |
|------|------|------|------|
| 1 | vendor/ 修改尝试 | 5 | 加强 Rules 中的说明 |
| 2 | 分号遗漏导致语法错误 | 3 | 在 Skill 模板中加注释 |

步骤三：建立闭环机制

违规发生 → 记录日志 → 统计报告 → 规则改进 → 验证效果

4.4.3 构建可视化仪表盘

步骤一：设计仪表盘功能

功能	说明
拖拽加载	支持拖入日志文件自动解析
Hook 耗时分布	直方图展示 Hook 性能
工作流阶段耗时	阶段时间线可视化
违规类型统计	饼图展示违规分布
每日事件趋势	折线图展示趋势变化

步骤二：技术选型

• 纯前端实现：数据不上传，保护隐私
• 单 HTML 文件：易于部署和维护
• ECharts：图表库，支持拖拽交互

4.5 第四步：持续迭代

4.5.1 问题闭环机制

发现问题 → 分析根因 → 制定改进 → 实施验证
    ↑                                    │
    └────────────────────────────────────┘
              教训固化为规则/技能

步骤一：问题收集

每次 AI 犯错或验收失败时记录：

• 问题描述
• 发生场景
• 根本原因
• 改进建议

步骤二：规则化

将有效教训固化为规则：

## 新增规则：防止重复错误

在 `auto-testing.md` 中增加：

### 禁止行为
- ❌ 跳过失败的测试不修复就标记 task 完成

步骤三：验证闭环

改进后观察相同问题是否再次发生，形成闭环。

4.5.2 规则依赖管理

步骤一：维护依赖图

每次新增规则时更新依赖关系：

graph TD
    AT[auto-testing]
    AD[auto-deploy]
    DV[deploy-verification]
    AE[anydev]
    
    AD -->|依赖| AT
    AD -->|依赖| DV
    DV -->|依赖| AE

步骤二：影响面分析

修改规则前检查连锁影响：

如果修改…	需要同步检查…
auto-testing	auto-deploy（依赖测试结果格式）
workflow-openspec	archive-commit-prompt、auto-deploy
anydev	deploy-verification、anydev-default-env

4.5.3 规则优先级维护

步骤一：冲突检测

当新规则与现有规则冲突时，按优先级裁决：

优先级	裁决原则
P0 > P1 > … > P5	高优先级优先
同优先级	始终生效 > 按需加载
仍有冲突	保守/安全优先

步骤二：规则清单维护

建立单一权威源（manifest.json）：

{
  "rules": [
    {
      "name": "auto-testing",
      "priority": "P3",
      "alwaysApply": true,
      "dependencies": []
    },
    {
      "name": "auto-deploy-after-test",
      "priority": "P3",
      "alwaysApply": true,
      "dependencies": ["auto-testing", "deploy-verification"]
    }
  ]
}

---

第五章：实践检验清单

在应用 Harness Engineering 方法论时，可按以下清单检验：

控制层检验

• [ ] 规则文档是否覆盖所有 AI 需要约束的行为？
• [ ] 规则是否区分「始终生效」和「按需加载」？
• [ ] 规则优先级是否明确（P0-P5）？
• [ ] 规则之间是否存在矛盾（依赖图是否维护）？
• [ ] 技能包是否覆盖所有关键领域？
• [ ] 技能包是否采用版本管理？
• [ ] 工作流是否包含明确的阶段划分？
• [ ] 每个阶段是否有验收标准（Gate）？
• [ ] 关键阶段是否需要人类确认？

执行层检验

• [ ] Hook 是否在关键节点执行？
• [ ] Hook 是否支持跨平台（Windows/macOS/Linux）？
• [ ] Hook 失败是否阻止继续？
• [ ] Hook 是否自动记录日志？
• [ ] 子 Agent 是否有明确的职责边界？
• [ ] 子 Agent 是否可按需调用？
• [ ] 外部工具集成是否已配置？

观测层检验

• [ ] 日志是否采用统一格式？
• [ ] 是否覆盖所有关键指标？
• [ ] 违规事件是否自动记录？
• [ ] 是否生成定期统计报告？
• [ ] 是否有可视化仪表盘？
• [ ] 是否建立问题闭环机制？

---

附录：术语表

术语	定义
Harness	约束装置，将 AI 能力引导到可控轨道
Rules	规则约束，对 AI 行为的软约束
Hooks	生命周期钩子，对 AI 行为的硬约束
Skills	技能包，封装领域知识
Workflows	工作流，结构化任务执行流程
Agents	子 Agent，专项任务自动化
Gate	阶段验收门禁
SemVer	语义化版本（Major.Minor.Patch）

第六章：Harness Engineering 实践工程案例 mydemoPro

基于 Harness Engineering 理念的业务项目开发工作区，在AI IDE codebuddy 下集成 AI 驱动的结构化工作流、规则约束和技能包系统。

项目结构

mydemoPro/
├── app/                          # 应用代码
│   └── anybusiness/         # 业务代码（swoole + PHP）
│       ├── business_logic/
│       │   ├── controller/       # 控制器（业务入口）
│       │   ├── Dao/              # 数据访问层（分表支持）
│       │   ├── Service/          # 服务层（API/缓存/发奖）
│       │   ├── Testcase/         # 单元测试
│       │   │   ├── controller/   # 控制器测试
│       │   │   └── reports/      # 测试报告（不提交）
│       │   └── phpunit.xml       # PHPUnit 配置
│       ├── doc/                  # 业务文档（Wiki/SQL/模板）
│       └── publish_script/       # 部署脚本
├── openspec/                     # OpenSpec 结构化变更管理
│   ├── changes/                  # 活跃变更
│   ├── changes/archive/          # 已归档变更
│   └── specs/                    # 持久化接口规格（系统行为契约）
├── .codebuddy/                   # AI 协作配置
│   ├── agents/                   # 子 Agent（代码审查）
│   ├── hooks/                    # 生命周期钩子 + 监控工具（Python 跨平台实现）
│   ├── logs/                     # 运行时监控 + 违规审计日志（不提交）
│   ├── rules/                    # 项目规则（团队共享约束，manifest.json 为元数据权威源）
│   ├── scripts/                  # 规则校验、流程 Gate 等工程化脚本
│   ├── skills/                   # 技能包（领域知识封装，含版本管理）
│   ├── commands/                 # 自定义命令（/opsx:*、/dev:* 等）
│   ├── dashboard.html            # 度量仪表盘（本地可视化）
│   └── settings.json             # Hooks + 全局配置
├── doc/                          # 文档导航 + 教程
├── CONTEXT.md                    # AI 快速上下文入口（新会话读此文件）
├── .editorconfig                 # 代码风格统一配置
└── .gitignore                    # Git 忽略规则

Harness Engineering 要素

1. 规则约束（Rules）

位于 .codebuddy/rules/，对 AI 行为进行结构化约束。规则元数据以 .codebuddy/rules/manifest.json 为单一权威源，可通过 .codebuddy/scripts/validate-rules.py 校验：

规则文件	始终生效	说明
workflow-openspec.md	✓	OpenSpec 流程启动确认 + Apply 验收规则（仅适用于 app/ 业务代码）
env-windows-shell.md	✓	Windows Shell 安全约束，禁止 Linux 语法
meta-memory-storage.md	✓	记忆存储位置确认（个人记忆 vs 项目规则）
auto-testing.md	✓	自动测试规则：目录结构、命名规范、执行策略、报告本地保存
auto-deploy-after-test.md	✓	单元测试通过后自动执行部署验证，无需询问
git-commit-confirmation.md	✓	Git 提交推送必须用户明确确认，禁止自动执行
credential-safety.md	✓	禁止未经确认删除本地凭证，认证问题先排查再操作
file-modify-confirmation.md	✓	业务代码（app/）修改必须用户确认后才执行
archive-commit-prompt.md	—	归档完成后提示用户是否需要提交和推送代码
dev-skill-naming.md	—	Skill 命名约定（my- 开头为个人）
anydev.md	—	AnyDev 云研发集成部署规则
deploy-verification.md	—	远程环境部署验证标准流程（Docker + curl 接口调用）
anydev-default-environment.md	—	AnyDev 默认环境配置（免交互式选择）
runtime-monitoring.md	—	运行时监控：Hook 执行耗时、测试/部署耗时追踪
violation-audit.md	—	约束违规审计：拦截事件记录、违规模式统计
rule-priority.md	—	规则优先级体系（P0-P5）与冲突检测策略
skill-versioning.md	—	技能包版本管理规范（SemVer + CHANGELOG）
rule-dependency-graph.md	—	规则依赖关系图（依赖/协作/互斥/特化）

规则维护时先更新 .codebuddy/rules/manifest.json，再运行校验脚本，避免规则清单、优先级和依赖关系漂移：

python .codebuddy/scripts/validate-rules.py

执行说明：当前该校验脚本属于半自动规则维护 Gate，尚未接入 Git Hook / CI 强制执行。AI 修改规则时应主动运行；人工修改规则时需要手动运行。后续可升级为 CodeBuddy PostToolUse Hook 或 Git pre-commit，在规则文件变更后自动校验并阻止不一致提交。

2. 技能包（Skills）

每个技能包遵循 SemVer 版本管理，包含 SKILL.md（定义 + 版本号）和 CHANGELOG.md（变更日志）。

项目级技能（.codebuddy/skills/）

技能包	版本	说明
openspec-propose	1.0.0	提出变更，生成提案/设计/任务
openspec-apply-change	1.0.0	按任务清单实施代码，完成后提示部署验证
openspec-archive-change	1.0.0	归档已完成的变更
openspec-explore	1.0.0	探索模式，讨论需求
my-swoole-env-check	1.0.0	检查 Swoole + PHP 运行环境（个人，不提交）

用户级技能

技能包	说明
game-activity-backend	游戏活动后端开发：代码模板、Dao 分表、奖励配置、建表语句、测试用例
reward-logic-validator	奖励逻辑验证：资格检查、超发风险、并发安全、反模式识别

3. 结构化工作流（OpenSpec）

每次业务代码变更遵循 propose → review → test-design → apply → verify → functional-test → archive 流程：

1. Propose — 生成 proposal + design + tasks
2. Review — 需求评审（⚠️ 待实现）
3. Test Design — 测试用例编写（⚠️ 待实现）
4. Apply — 逐步实施任务，每步验收（语法检查、路由验证等）
5. Verify — 部署到远程环境调试验证（可选）
6. Functional Test — 自动化功能测试（⚠️ 待实现）
7. Archive — 完成后归档，同步规格到 openspec/specs/

工具支持: OpenSpec CLI v1.3.1（npm install -g @fission-ai/openspec@latest）。
当然支持 AI编程 结构化工作流 Spec 的工具框架有很多，比如Spec-Kit、OpenSpec、Superpowers等等，是可以自行根据需要选择的。

4. 子 Agent（Agents）

位于 .codebuddy/agents/，提供专项自动化能力：

Agent	说明
code-reviewer	代码审查：检查业务逻辑流程、Dao 规范、命名约定、安全风险

触发方式：完成代码编写后请求"代码审查"或"review"即可自动调用。

5. Hooks（生命周期钩子）

位于 .codebuddy/hooks/，在 AI 执行操作的关键节点确定性执行自定义脚本。当前启用 Hook 采用 Python 实现，以提升 Windows / PowerShell、macOS、Linux 多环境兼容性。

与 Rules 的区别：Rules 是"建议性约束"（依赖 AI 自觉遵守），Hooks 是"强制性约束"（系统保证执行）。

Hook 脚本	事件	触发时机	说明
php-lint.py	PostToolUse	每次编辑/创建文件后	自动对 PHP 文件执行 php -l 语法检查，失败则阻止继续
file-protect.py	PreToolUse	每次写入/编辑文件前	阻止修改 vendor/、.git/、.env、node_modules/
monitor-logger.sh	—	旧版 Bash Hook 引用	运行时监控日志工具，记录执行耗时
violation-logger.sh	—	旧版 Bash Hook 引用	违规审计日志工具，记录拦截事件

配置文件: .codebuddy/settings.json

{
  "hooks": {
    "PreToolUse": [{ "matcher": "Write|Edit", "hooks": [{ "type": "command", "command": "...file-protect.py" }] }],
    "PostToolUse": [{ "matcher": "Write|Edit", "hooks": [{ "type": "command", "command": "...php-lint.py" }] }]
  }
}

设计理念：将 auto-testing 规则中的语法检查从"AI 应该做"升级为"系统保证执行"，形成双保险。

Hook 脚本变更后可执行语法检查：

python -m py_compile .codebuddy/hooks/file-protect.py .codebuddy/hooks/php-lint.py

6. 集成（Integrations）

集成	状态	说明
AnyDev 云研发	已连接	远程环境部署、WebShell 执行、文件上传
企业微信 AiBot	已对接	通过企微消息驱动 AI 执行开发任务

企业微信对接说明

本项目已实现通过 企业微信（WeCom）AiBot 与 CodeBuddy IDE 对接，支持在企微聊天中直接：

• 提出需求 → 触发 OpenSpec 流程
• 查看项目状态、Git 状态
• 驱动代码修改、测试、归档等操作

7. 持久化记忆（Memory）

项目使用了 CodeBuddy 的持久化记忆功能，用于跨会话保留关键约束和经验教训，确保 AI 在任何新会话中都能自动遵循已建立的规范。

8. 闭环反馈

• 每次 AI 犯错，将教训固化为 Rule 或 Skill 改进，或写入持久化记忆
• 验收标准强制执行（语法检查、路由验证等）
• 规则持续迭代，不断收紧约束

9. 可观测性与治理

9.1 运行时监控

追踪 AI 协作过程中的关键性能指标：

监控维度	内容	日志位置
Hook 执行耗时	每次 Hook 的执行时间（ms）	.codebuddy/logs/monitor-*.log
测试执行耗时	单元测试套件运行时间	同上
部署验证耗时	上传 → 验证通过的总时间	同上
OpenSpec 阶段耗时	各阶段（propose/apply/verify/archive）耗时	同上

日志格式为 JSON 行，示例：

{"ts":"2026-05-09T14:00:00","event":"hook_exec","source":"php-lint","target":"controller/Foo.php","duration_ms":120,"result":"pass"}

9.2 约束违规审计

记录每次 Hook 拦截事件，形成可分析的审计数据：

• 日志: .codebuddy/logs/violations/violations-*.jsonl
• 统计报告: violations-summary.md（定期更新）
• 趋势分析: 违规连续 3 天上升时主动建议加强规则
• 模式识别: 同类违规累计超 5 次时建议新增预防性规则

{"ts":"2026-05-09T14:00:00","hook":"file-protect","action":"blocked","target":"vendor/autoload.php","pattern_matched":"vendor/","context":"尝试修改受保护路径"}

9.3 规则优先级与冲突检测

19 条规则按 P0-P5 六级优先级分类，确保规则增多后 AI 有明确决策依据：

优先级	类别	说明	示例
P0	安全硬约束	Hooks 强制执行，不可违反	file-protect.py、php-lint.py
P1	安全软约束	凭证/数据安全	credential-safety.md
P2	流程约束	工作流程控制	workflow-openspec.md
P3	质量约束	测试/部署质量	auto-testing.md
P4	行为约束	AI 行为偏好	env-windows-shell.md
P5	领域指导	开发技能/命名	dev-business-anyone-skill.md

冲突处理原则：高优先级 > 低优先级 > 始终生效 > 按需加载 > 保守/安全优先。

9.4 规则依赖关系图

通过 rule-dependency-graph.md 维护 19 条规则之间的 4 类关系（Mermaid 可视化）：

关系类型	含义	当前数量
依赖 (→)	A 的执行前提是 B 已建立	11
协作 (↔)	A 和 B 互相补充	3
特化 (⚡)	A 在特定场景覆盖 B 的通用行为	1
互斥 (✕)	A 和 B 不可同时满足	0

影响面分析：修改任何规则前，查阅依赖图确认连锁影响，避免引入规则间矛盾。

9.5 度量仪表盘

提供本地可视化 HTML 仪表盘（.codebuddy/dashboard.html），支持：

• 拖拽加载 monitor-*.log 和 violations-*.jsonl 日志文件
• 自动解析并展示：Hook 耗时分布、OpenSpec 阶段耗时、违规类型统计、每日事件趋势
• 纯前端实现，数据不上传，本地浏览器直接打开即可

使用方式：在浏览器中打开 .codebuddy/dashboard.html，拖入日志文件查看。

快速开始

# 安装 OpenSpec CLI
npm install -g @fission-ai/openspec@latest

# 验证安装
openspec --version  # 当前: 1.3.1

# 在 CodeBuddy 中提出一个新变更
/opsx:propose 你的需求描述

# 实施变更
/opsx:apply

# 归档
/opsx:archive

约定

文件组织原则

• 规则文件扁平化: .codebuddy/rules/ 下所有规则为 .md 文件，不嵌套子目录
• 规则元数据权威源: .codebuddy/rules/manifest.json 统一维护规则清单、优先级和依赖关系
• 单一权威源: 同一文档只保留一份，通过引用指向而非拷贝
• AI 上下文入口: 新会话建议先读 CONTEXT.md 快速建立项目认知
• 人类导航入口: 新人建议先读 doc/README.md 按场景找文档

提交约定

• 个人自定义 Skill 以 my- 开头，不提交到仓库（已在 .gitignore 中排除）
• 团队共享规则存放在 .codebuddy/rules/
• app/ 下的业务代码变更走 OpenSpec 流程管理
• .codebuddy/、openspec/、工具链配置等非业务变更直接执行，无需走流程
• vendor/ 目录需要提交（确保部署环境依赖一致）
• 测试报告 (Testcase/reports/) 仅本地保存，不提交到仓库
• 单元测试代码 (Testcase/*.php) 随业务代码一起提交
• 备份文件（*.bak、*.sh_bak）不提交到仓库

总结

有的同学要说了，这都讲完了一篇文章了，也没看懂具体要怎么做呀？其实小马为这本身就还没有什么标准的流程，因为驾驭工程目前不也就是个概念和范式吗？当然，不就的将来会有什么 Harness Engineering 的标准框架出来那就不得而知了。

但话又说回来，只要能理解 Harness Engineering 的概念，完全是可以 借助AI 一步一步 逐渐完善你的 Harness Engineering 环境的，只要注意做好闭环反馈的机制，它就是可以一步步进化的，更何况每个项目都是具有其自己的特征的。OpenAI号称他们的 Harness Engineering 实践代码就是零人工参与的，其实就是一个道理。

非要说个开始的吧，那就是加载你的业务代码，外面套一下 环境设计的目录，加载一个开源的Spec工作流，用上 SKILL、rule等几大要素的技能，设置闭环反馈机制 就可以开始一步步建设你的 Harness Engineering 了，不懂的就问AI就行了。

如果还学不会 Harness Engineering 实践 落地，可以联系小马吧哈。