Harness-OSPX

A lightweight, AI-native project scaffolding toolkit based on Harness Engineering + OpenSpec methodology.

基于 Harness Engineering + OpenSpec 方法论的轻量级、AI 原生项目脚手架工具包。

这是什么？

Harness-OSPX 帮助你初始化一套结构化的工程驾驭系统（Harness），用于 AI Agent 驱动的开发模式。它提供：

• Skill 引导式初始化 — 在 AI 对话中通过苏格拉底式问答完成项目骨架搭建
• 骨架模板 — 开箱即用的工程文档（AGENTS.md、架构约束、迭代指南等）
• 架构预设 — 常见项目类型的分层架构快速启动配置
• Harness 命令体系 — 基础命令 + 基础 Skill + init 命令/Skill（+ 可选 Code Review），覆盖从需求到归档的完整迭代闭环（详见 CHANGELOG）
• 可选增强模块 — 上下文管理、增强型自验证、独立 Code Review Agent、可拆卸 Prompt 模板

核心理念

Harness Engineering 是"骨架"（流程 + 约束 + 验证）。 OpenSpec 是"内容"（需求 + 设计 + 任务）。

本工具包提供骨架，你为具体项目填入内容。

职责边界

| 维度 | Harness（骨架） | OpenSpec（内容） | |------|----------------|-----------------| | 管辖目录 | harness/ + AGENTS.md + scripts/ | openspec/ | | 核心职责 | 约束与验证（做对） | 需求规划与管理（做什么） | | 产出物 | 架构约束、迭代指南、门控脚本、熵治理规则 | proposal、specs、design、tasks | | 规则类型 | 执行流程约束（如"连续失败 3 次停止"） | 内容质量标准（如"spec 应包含 WHEN/THEN"） |

快速开始

首次安装

将 harness-init Skill 安装到你的 AI 编码助手（一次性操作）：

npx @pxp995/harness-ospx install

CLI 会自动检测已安装的工具（CodeBuddy / Claude Code / Cursor），也可以手动指定：

npx @pxp995/harness-ospx install --tools codebuddy,claude-code

方式一：AI 对话引导（推荐）

安装完成后，在 AI 编码助手中使用命令或 Skill：

/harness:init

或者直接说「初始化 Harness 骨架」「搭建新项目」等，AI 会通过 harness-init Skill 自动触发，经历苏格拉底式引导完成项目配置，生成所有骨架文件。

命令和 Skill 定义位于 skeleton/.codebuddy/commands/harness/init.md 和 skeleton/.codebuddy/skills/harness-init/SKILL.md。

方式二：手动设置

1. 将 skeleton/ 目录内容复制到项目根目录（注意包含隐藏目录 .codebuddy/ 和 .husky/，使用 cp -r skeleton/. . 或 rsync -a skeleton/ .）
2. 编辑每个文件中的模板变量（<!-- VARIABLE:xxx --> 标记）
3. 根据项目需求自定义 openspec/config.yaml
4. 安装门控脚本依赖，配置 Git Hooks

使用流程全景

Phase 1 — 初始化（一次性）

加载 Skill → 苏格拉底引导 → 生成配置 → 渲染骨架 → 工程初始化 → 增强模块 → 完成

Skill 引导的 6 个 Phase：

| Phase | 做什么 | 产出 | |-------|--------|------| | 1. 理解意图 | 苏格拉底式提问（项目类型、技术栈、架构分层） | 用户意图 + 预设匹配 | | 2. 生成配置 | 组装 harness.config.yaml 并请用户确认 | 完整配置文件 | | 3. 渲染骨架 | 读取 skeleton/ 模板，替换变量，写入项目 | AGENTS.md + harness/ + openspec/ | | 4. 工程初始化 | 生成工程文件、源码骨架、门控脚本、Git Hooks、命令/Skill | 可运行的项目 + 门控体系 + 命令体系 | | 5. 增强模块 | 可选添加上下文管理、增强验证、Prompt 模板 | supplements → harness/ | | 6. 完成确认 | 展示文件清单、验证结果、可用命令 | 项目就绪 |

Phase 4 是核心——骨架文件（文档）和可运行项目是两件事，Phase 3 生成文档，Phase 4 让项目跑起来。

Phase 2 — 日常迭代（反复循环）

初始化完成后，每次功能迭代按 6 步闭环 执行：

① 需求定义 (OpenSpec)  →  ② 影响分析 (OpenSpec)  →  ③ 任务拆解 (OpenSpec)
          ↑                                                    ↓
⑥ 归档同步 (两者)      ←  ⑤ 验证门控 (Harness)   ←  ④ Agent 开发 (两者)

每个步骤都有对应的 Harness 命令：

| 步骤 | 命令 | 做什么 | 核心约束 | |------|------|--------|---------| | ① ② ③ | /harness:propose "描述" | 需求定义 + 影响分析 + 任务拆解 | 内部调用 /opsx:propose + Harness 分层约束注入 | | ④ | /harness:apply | 按任务清单开发 | 开发节奏：写码→验证→测试→有效性；失败 3 次停止 | | ⑤-工程 | /harness:verify | 运行门控脚本 | verify + test + check-docs（自动化） | | ⑤-需求 | /harness:review | 对照 spec 验证代码 | 完整性 + 正确性 + 一致性（Agent 审查） | | ⑥ | /harness:archive | 归档同步 | 自动化门控 → 人工阻断确认 → 迭代记录 |

辅助命令：

| 命令 | 做什么 | |------|--------| | /harness:status | 展示项目状态（进行中变更包、未完成 tasks） | | /harness:continue | 从中断处恢复开发 | | /harness:fix "描述" | 快速修 Bug（简化版：propose → apply → verify → archive） |

Skill 覆盖范围：propose / apply / verify / review / archive 五个核心命令有对应的 Skill（支持意图匹配触发）。status / continue / fix 三个辅助命令仅支持显式命令触发，不设 Skill。

Phase 3 — 持续改进（每次迭代后）

迭代教训 → 写入迭代记录 → 是否跨项目通用？
                            ├── 是 → 标记 TEMPLATE_CANDIDATE → 人类审阅 → 合入模板
                            └── 否 → 写入项目 harness/（仅项目级）

常见迭代场景

场景 A：新增功能

/harness:propose "新增 XX 功能"     ← ①②③ 生成完整变更包
  审阅 proposal + design + tasks
/harness:apply                      ← ④ 按任务逐步开发
/harness:verify                     ← ⑤ 工程验证
/harness:review                     ← ⑤ 需求验证
/harness:archive                    ← ⑥ 归档 + 迭代记录

场景 B：修 Bug

/harness:fix "XX Bug 描述"          ← 简化流程，一条命令搞定

场景 C：从中断恢复

/harness:status                     ← 查看当前状态
/harness:continue                   ← 从最后一个完成的 Task 继续

初始化后的项目结构

your-project/
│
├── AGENTS.md                       # Agent 工作导航（每次对话必读）
│
├── openspec/                       # OpenSpec — 内容（需求 + 设计 + 任务）
│   ├── config.yaml                 #   项目配置（技术栈 + 内容质量规则）
│   ├── specs/                      #   当前生效的能力 spec（单一真相源）
│   │   └── data-model.md           #   数据模型定义
│   └── changes/                    #   变更管理
│       └── archive/                #   归档（完成的变更包快照）
│
├── harness/                        # Harness — 骨架（流程 + 约束 + 验证）
│   ├── architecture.md             #   架构约束（分层规则、依赖矩阵）
│   ├── data-model.md               #   数据建模约束（命名规范、变更流程）
│   ├── tasks.md                    #   任务管理规则（流程约束 + 格式参考）
│   ├── iteration-guide.md          #   迭代流程指南（6 步闭环 + 开发节奏）
│   ├── entropy-rules.md            #   熵治理规则（自动化 + 人工阻断）
│   ├── directory.md                #   目录结构（目录维度唯一真相源）
│   └── archive/iterations/         #   迭代记录归档
│
├── .codebuddy/                     # Harness 命令 + Skill
│   ├── commands/harness/           #   8 个基础命令 + 1 个可选（显式触发）
│   │   ├── propose.md
│   │   ├── apply.md
│   │   ├── verify.md
│   │   ├── review.md
│   │   ├── archive.md
│   │   ├── status.md
│   │   ├── continue.md
│   │   ├── fix.md
│   │   └── code-review.md         #   可选（启用 Code Review Agent 时）
│   └── skills/harness-*/           #   5 个基础 Skill + 1 个可选（意图匹配触发）
│
├── scripts/                        # 门控脚本
│   ├── lint-arch.ts                #   架构约束检查（依赖方向、文件大小、命名）
│   ├── check-docs.ts               #   文档一致性检查（6 项自动化检查）
│   ├── verify.sh                   #   综合验证编排
│   └── pre-commit.sh               #   提交前门控编排
│
├── .husky/pre-commit               # Git Hook — 提交时自动触发门控
└── src/                            # 源码（按架构分层组织）

信息查找指引

| 想找什么 | 去哪里 | |---------|-------| | 项目全貌和规则 | AGENTS.md | | 迭代该怎么做 | harness/iteration-guide.md | | 某个功能的需求 spec | openspec/specs/<能力>/spec.md | | 某次迭代的变更包 | openspec/changes/archive/<日期-功能名>/ | | 某次迭代的经验教训 | harness/archive/iterations/<功能名>.md | | 架构约束和依赖矩阵 | harness/architecture.md | | 数据模型定义 | openspec/specs/data-model.md | | 数据建模约束 | harness/data-model.md |

开发节奏（每个 Task）

Agent 在执行每个 Task 时 MUST 遵循以下节奏：

1. 写代码
   ↓
2. 运行架构检查 + 类型检查
   ├── 通过 → 继续
   └── 失败 → 修复重试（连续失败 3 次 → 停止，请求人类介入）
   ↓
3. 写配套测试
   ↓
4. 运行测试
   ├── 通过 → 继续
   └── 失败 → 修复重试（连续失败 3 次 → 停止）
   ↓
5. 验证测试有效性（注释掉核心逻辑 → 测试应该失败）
   ├── 测试失败 → 好，恢复源码
   └── 测试仍通过 → 测试无效，补充断言，回到 4
   ↓
6. 标记 Task [x]，进入下一个

硬性终止：单 Task 总验证循环（步骤 2+4+5 累计）不超过 10 次。

验证门控体系

三级门控

| 时机 | 跑什么 | 触发方式 | |------|--------|---------| | 开发中 | 单文件测试 | 手动 | | 提交时 | 综合验证 + 测试 + 文档检查 | Git Hook（Husky）自动触发 | | 归档前 | 自动化门控 + 人工阻断检查 | /harness:archive 流程内 |

verify vs review

| | /harness:verify | /harness:review | |---|---|---| | 验什么 | 架构约束（结构层面） | 完整性 + 正确性 + 一致性（语义层面） | | 怎么验 | 自动化脚本 | Agent 逐条对照 spec 场景 | | 报告级别 | 通过 / 失败 | CRITICAL / WARNING / SUGGESTION |

熵治理（归档时）

• 自动化检查（E-A1~E-A6）：directory.md 一致性、数据模型一致性、文档链接有效性、OpenSpec 版本一致性、教训反哺完整性
• 人工阻断检查（E-M1~E-M5）：规则摘要一致性、规则冲突排查、硬编码扫描、教训反哺确认、模板反哺判定

工具包目录结构

harness-ospx/
├── schema/                       # 配置约束
│   └── harness.config.schema.yaml
├── presets/                      # 架构预设（仅骨架，不锁定技术栈）
│   ├── react-spa.yaml
│   ├── node-api.yaml
│   └── fullstack.yaml
├── skeleton/                     # 项目骨架模板
│   ├── AGENTS.md                 #   Agent 导航模板
│   ├── .husky/pre-commit         #   Git Hook 模板
│   ├── scripts/                  #   门控脚本模板（4 个）
│   ├── harness/                  #   Harness 文档模板（6 个）
│   ├── openspec/config.yaml      #   OpenSpec 配置模板
│   └── .codebuddy/               #   命令 + Skill 模板 + init（仅工具包级，不写入目标项目）
├── supplements/                  # 可选增强模块
│   ├── context-management.md     #   上下文管理（架构 + 隔离）
│   ├── self-verification.md      #   增强型自验证（状态指纹、分级升级）
│   ├── code-review-agent.md      #   独立 Code Review Agent（Sub-Agent 审查）
│   └── prompt-templates/         #   可拆卸 Prompt 模板
├── CHANGELOG.md                  # 版本变更记录
├── LICENSE                       # MIT
└── README.md                     # 本文件

可选增强模块

初始化完成后可按需添加：

| 模块 | 文件 | 覆盖内容 | 推荐度 | |------|------|---------|-------| | 上下文管理 | context-management.md | 信息优先级分层（P0~P3）、延迟加载、任务级隔离、长会话压缩 | 推荐 | | 增强型自验证 | self-verification.md | 状态指纹检测、分级错误升级（Level 0~3）、评估分离策略 | 可选 | | Prompt 模板 | prompt-templates/ | 可拆卸的任务执行 Prompt（实现/测试/审查） | 可选 | | Code Review Agent | code-review-agent.md | 独立 Sub-Agent 代码审查，每个 Task 完成后自动触发，5 维度审查 | 推荐 |

添加方式：将 supplements/ 下的文件复制到项目 harness/ 目录，并在 AGENTS.md 文档索引中添加对应条目。

兼容性

本工具包生成标准的 Markdown + YAML 文件，可在任何支持读取项目文件的 AI 编码助手中使用：

• CodeBuddy
• Cursor
• Claude Code
• GitHub Copilot Workspace
• 任何支持 AGENTS.md / system prompt 的工具

OpenSpec 版本兼容性

Harness-OSPX 依赖 OpenSpec 作为内容层（需求 + 设计 + 任务）。

| Harness-OSPX | OpenSpec | 说明 | |:------------:|:--------:|------| | v1.0.0 | ≥ 1.2.0 | 需要 Core Profile 命令（explore / propose / apply / archive） |

初始化时的 OpenSpec 安装：/harness:init 的 Phase 4 会自动安装 OpenSpec 命令和 Skill（优先使用 openspec init，降级为 npx @fission-ai/openspec@latest init）。

版本锁定：初始化时的 OpenSpec 版本会记录在 harness.config.yaml 的 meta.openspec_version 和 harness/iteration-guide.md 的命令参考表中。如 OpenSpec 版本升级导致命令变更，以 OpenSpec 官方文档为准。

双层反馈机制

项目实践中积累的经验教训可以反哺到模板中持续改进：

项目迭代 → 沉淀教训 → 是否跨项目通用？
                        ├── 是 → 标记为 TEMPLATE_CANDIDATE → 人类审阅 → 合入模板
                        └── 否 → 写入项目的 harness/（仅项目级）

反馈条目通过 GitHub Issues 跟踪。

许可证

MIT