harness-engineer

一个以仓库为中心、面向长期 AI 协作上下文的 CLI。

harness-engineer 是一个用于初始化仓库级 AI 协作文档的 npm CLI。

安装后会提供 harness 命令，用来在仓库里建立一套持久、file-first 的工作上下文，让 Codex 和其他 agent 依赖仓库文件协作，而不是依赖一个越来越长的提示词或一段会消失的聊天记录。

English README

为什么会有这个项目

很多 AI 辅助开发仓库都会遇到同样的问题：

• 规则散落在提示词、聊天记录和个人笔记里
• 架构背景缺失或很快过期
• 多步骤工作没有可追溯的执行记录
• 每次新开 agent 会话都要重新理解仓库

harness-engineer 的做法是把这套上下文直接落到仓库里：

• HARNESS_BOOTSTRAP.md 作为 orchestrator 激活协议和运行时入口
• AGENTS.override.md 作为 Codex 协作指南和启动触发器
• .codex/config.toml 与 .codex/agents/*.toml 作为项目级 subagent 配置
• ARCHITECTURE.md 记录系统边界与改动影响
• docs/ 记录产品、设计、安全、可靠性、参考资料和执行计划
• harness-engineer.config.json 让后续 CLI 命令理解当前仓库的 harness 配置

核心创新：运行时激活层

与普通脚手架工具不同，harness-engineer 提供了运行时激活层：

• HARNESS_BOOTSTRAP.md 定义了 Codex 的首轮协议
• 通过任务分类和委派规则强制 orchestrator 模式
• harness start 提供标准化激活提示词，替代手动输入
• 仓库现在会以可预测、协调优先的模式启动 Codex

核心亮点

• 同时支持空项目初始化和已有仓库补全
• 生成真实文件模板，而不是把 markdown 大段硬编码进 TypeScript
• 提供 harness enrich，对已有仓库执行受约束的 codex exec 文档补全
• 提供 harness start 实现可靠的 orchestrator 模式激活
• 支持 en、zh、bilingual 三种输出模式
• 通过 harness status 检测受管理文档缺失和漂移
• 通过 harness task 创建和归档可长期维护的执行计划

环境要求

• Node.js >= 20
• 任意可安装 npm 包的包管理器，例如 npm 或 pnpm
• 如果要使用 harness enrich：本地需要可用的 Codex CLI，并且已经登录

安装

全局安装：

npm install -g harness-engineer

安装后会在 PATH 中暴露一个命令：

harness --version

如果安装后仍然找不到 harness，通常是 npm global bin 目录还没有加入 PATH。

开始使用

1. 初始化一个新项目

mkdir acme-platform
cd acme-platform
harness init . --project-name "Acme Platform" --yes

2. 在 harness 模式下开始与 Codex 协作

harness start

复制 harness start 的输出，作为你在 Codex 中开启新会话的第一个提示词。这将激活 orchestrator 模式和正确的委派规则。

3. 补全一个已有仓库

cd existing-repo
harness enrich . --yes

这条命令会：

1. 补齐缺失的 harness 基线文件
2. 创建或刷新 HARNESS_BOOTSTRAP.md 用于运行时激活
3. 不去修改现有业务代码
4. 调用 codex exec，基于仓库事实补全文档背景信息

补全后，运行 harness start 获取你的激活提示词。

4. 创建和追踪执行计划

harness task new 2026-04-02-auth-debug --class B
harness status

脚手架总览

默认的 generic-software preset 会生成类似这样的结构：

.
├── HARNESS_BOOTSTRAP.md          ← 运行时激活协议
├── AGENTS.override.md
├── ARCHITECTURE.md
├── harness-engineer.config.json
├── .codex/
│   ├── config.toml
│   └── agents/
│       ├── orchestrator.toml
│       ├── planner.toml
│       ├── builder.toml
│       ├── reviewer.toml
│       └── tester.toml
└── docs/
    ├── index.md
    ├── DESIGN.md
    ├── FRONTEND.md
    ├── PLANS.md
    ├── PRODUCT_SENSE.md
    ├── QUALITY_SCORE.md
    ├── RELIABILITY.md
    ├── SECURITY.md
    ├── design-docs/
    ├── exec-plans/
    ├── generated/
    ├── product-specs/
    └── references/

CLI 命令参考

harness start

生成用于 harness 模式下 Codex 的标准化激活提示词。

harness start

这条命令会检查仓库状态，并输出一份启动提示词，用于：

• 指示 Codex 首先读取 HARNESS_BOOTSTRAP.md
• 定义 orchestrator 角色和委派规则
• 显示当前活跃执行计划和缺失文件
• 提供任务路由的快速参考

在 Codex 中开启新会话时，将此输出作为第一个提示词复制粘贴。

harness init

在新目录或尚未建立 harness 基线的目录中初始化脚手架。

harness init [target-directory] \
  [--project-name <name>] \
  [--preset generic-software] \
  [--language en|zh|bilingual] \
  [--force] \
  [--yes] \
  [--dry-run]

说明：

• target-directory 默认为 .
• --project-name 不传时会根据目录名自动推断
• --yes 跳过非空目录确认
• --force 刷新受 harness 管理的文件
• --dry-run 只预览写入计划，不真正落盘

harness enrich

先补齐已有仓库缺失的 harness 文件，再调用 Codex 补完项目背景文档。

harness enrich [target-directory] \
  [--project-name <name>] \
  [--preset generic-software] \
  [--language en|zh|bilingual] \
  [--force] \
  [--yes] \
  [--dry-run]

说明：

• 面向已有仓库，不适用于空目录
• 在 Codex 运行前，只会创建或刷新受 harness 管理的文档
• 不会修改业务代码、依赖、锁文件或 CI 配置
• --dry-run 会同时跳过文件写入和 Codex 调用

harness task new

基于 docs/exec-plans/template.md 创建执行计划。

harness task new <slug> --class A|B|C

harness task archive

把活动计划移动到 docs/exec-plans/completed/，并在必要时补上收尾章节。

harness task archive <slug>

harness status

检查当前仓库的 harness 健康度。

harness status

会报告：

• 当前活跃计划
• 缺失的受管理文件
• 已漂移的受管理文件
• 缺少必要章节的执行计划

激活 Harness 模式

让 Codex 进入 harness orchestrator 模式：

1. 初始化或补全后：

   harness start

2. 复制输出内容，作为在 Codex 中的第一个提示词。

3. Codex 将会：

   • 读取 HARNESS_BOOTSTRAP.md 理解自己的角色
   • 遵循首轮协议进行任务分类和委派
   • 作为 orchestrator 而非通用助手运行

4. 重新打开仓库？ 再次运行 harness start 获取新的激活提示词。

这种标准化激活确保跨会话的一致行为，无需维护手动提示词模板。

语言模式

harness-engineer 支持三种语言模式：

• en：生成英文文档
• zh：生成中文文档
• bilingual：在同一份 markdown 中同时生成英文与中文内容

这套语言模式同时适用于 init、enrich，以及后续 harness task 使用的执行计划模板。

enrich 的工作方式

harness enrich 默认是保守的，并且运行时感知（runtime-aware）。

在调用 Codex 之前，CLI 会先补齐受管理的基础文档。之后它会运行一段受约束的 codex exec prompt，明确要求 Codex：

• 通过 HARNESS_BOOTSTRAP.md 启用 orchestrator 模式
• 只在 harness 管理的文档范围内工作
• 基于仓库证据恢复上下文
• 不修改源码、依赖、锁文件和 CI
• 对不确定的信息明确标注，而不是凭空补全

补全过程确保：

1. HARNESS_BOOTSTRAP.md 包含任务分类和委派规则
2. AGENTS.override.md 在读取顺序中首先引用 HARNESS_BOOTSTRAP.md
3. orchestrator 角色与实现角色明确区分
4. 仓库已准备好进行 harness start 激活

因此它更适合”给现有代码库补文档背景”，而不是”做一条会改代码的迁移命令”。

协作角色模型

默认脚手架会文档化五个协作角色：

• Orchestrator
• Planner
• Builder
• Reviewer
• Tester

这些角色既会出现在生成的文档里，也会生成到 .codex/agents/ 下作为项目级 Codex custom agents，这样显式 subagent 委派时可以直接复用同一套词汇。

仓库工作流示例

# 初始化一个新仓库
harness init . --project-name "Acme Platform" --language bilingual --yes

# 获取激活提示词并启动 Codex
harness start
# （复制输出内容，作为在 Codex 中的第一个提示词）

# 创建执行计划
harness task new 2026-04-02-onboarding-flow --class B

# 检查当前 scaffold 健康度
harness status

# 或者给已有仓库补文档
harness enrich . --yes
harness start  # 在 Codex 中重新打开仓库时，始终使用 harness start

官方参考资料

如果你想进一步理解这个项目背后的 Codex 工作方式，下面这些 OpenAI 官方资料最值得先看：

• Codex CLI：理解 harness enrich 背后依赖的命令行运行方式
• Codex Subagents：理解项目级自定义 agent 和委派模式
• Codex Prompting Guide：学习如何编写更强的仓库上下文提示词
• OpenAI Developers Resources：查看更新的 Codex cookbook、指南和工作流文章

常见问题

harness: command not found

通常是 npm global bin 目录没有加入 PATH。重新打开终端，或者把 npm global bin 路径加入 shell profile。

harness enrich 提示找不到 Codex

先安装并登录 Codex CLI：

codex login

然后重新执行：

harness enrich . --yes

仓库里已经有自己的文档怎么办

这是正常情况。默认模式下，CLI 只会创建缺失的受管理文件。只有在你明确传入 --force 时，才会刷新 harness 管理的基线文档。

开发与验证

pnpm install
pnpm check
pnpm test:coverage
pnpm build

发布前建议执行：

pnpm release:check

npm 发布内容

发布到 npm 的包包含：

• dist/ 下的运行时代码
• templates/ 下的 scaffold 模板
• README.md、README.zh-CN.md、CHANGELOG.md 等包级文档

贡献与协作

欢迎贡献。如果你想改进 scaffold 结构、命令体验、模板质量或文档流程，可以先阅读 CONTRIBUTING.md。

许可证

本项目基于 MIT 许可证发布。

社区 / 项目活跃度

如果这个项目对你的工作流有帮助，给仓库点一个 Star 是支持项目、同时持续关注项目演进的最直接方式。

| 信号 | 活跃度 | | --- | --- | | GitHub Star 历史趋势 | |