# harness-engine **Repository Path**: toxcode/harness-engine ## Basic Information - **Project Name**: harness-engine - **Description**: harness-engine（驾驭引擎）：听起来像是一个强大的底层基础设施，非常契合你“可复用底座”的定位。 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-07-02 - **Last Updated**: 2026-07-08 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 🎛️ Enterprise AI Harness (企业级数字员工驾驭工程) > 本工程融合了 **harness-engine 企业级治理底座** + **Superpowers 软件开发方法论**，构建了一套完整的"受控数字员工"体系。 > > - **harness-engine 提供**：安全红线、角色定义、标准化 SOP、项目模板 > - **Superpowers 提供**：需求澄清 → 任务拆解 → 测试驱动 → 代码审查 → 验证完成的完整开发工作流 > > 通过本 Harness，AI 编程助手不再是"随机的聊天机器人"，而是遵循严格工程纪律、受控执行的"数字员工"。 ## 目录结构说明 ```text .harness/ ├── agents/ # 角色定义层（数字员工的"岗位说明书"） │ ├── coder.md # 编码专家：负责业务逻辑实现（已融合 Superpowers 纪律要求） │ └── reviewer.md # 评审专家：负责代码审查与安全合规检查（已融合审查决策 Gate） ├── rules/ # 全局治理层（不可逾越的"企业红线"） │ ├── security.md # 安全规范（禁止硬编码密钥、高危操作拦截等） │ ├── java-architecture.md # Java 架构与分层规范 │ ├── java-coding-standards.md # Java 编码级规范 │ └── development-process.md # ⭐ 新增：开发流程铁律（5 道 Hard-Gate） ├── skills/ # 技能体系层（标准化的"SOP 操作手册"） │ ├── unit-test/ # 编写单元测试的规范与工具链 │ ├── brainstorming/ # ⭐ 新增：需求澄清与方案设计 │ ├── writing-plans/ # ⭐ 新增：编写可执行计划 │ ├── test-driven-development/ # ⭐ 新增：测试驱动开发（RED→GREEN→REFACTOR） │ ├── systematic-debugging/ # ⭐ 新增：系统化调试（四阶段根因分析） │ ├── requesting-code-review/ # ⭐ 新增：结构化代码审查 │ └── verification-before-completion/ # ⭐ 新增：完成前三维验证 └── templates/ # 模板库（减少重复造轮子） └── prd-spec.md # 需求规格说明书模板 ``` --- ## 融合后的核心工作流 本 Harness 引入了 **Superpowers 的五阶段开发工作流**，每个阶段都有强制的 Gate 检查： ``` ┌─────────────────────────────────────────────────────────────────────────┐ │ 融合工作流（五阶段 + 五 Gate） │ ├─────────────────────────────────────────────────────────────────────────┤ │ Phase 1: Planning（规划） │ │ ├── brainstorming（需求澄清）→ 产出设计文档 │ │ └── writing-plans（任务拆解）→ 产出原子级计划 │ │ ⚠️ Hard-Gate 1: 未产出设计文档 → 禁止编码 │ │ ⚠️ Hard-Gate 2: 未产出可执行计划 → 禁止开始编码 │ ├─────────────────────────────────────────────────────────────────────────┤ │ Phase 2: Execution（执行） │ │ └── test-driven-development（RED→GREEN→REFACTOR） │ │ ⚠️ Hard-Gate 3: 未遵循 TDD → 代码回滚 │ ├─────────────────────────────────────────────────────────────────────────┤ │ Phase 3: Verification（验证） │ │ ├── requesting-code-review（结构化审查） │ │ └── verification-before-completion（三维验证） │ │ ⚠️ Hard-Gate 4: 未通过验证 → 不得标记完成 │ │ ⚠️ Hard-Gate 5: 未通过审查 → 禁止合并 │ ├─────────────────────────────────────────────────────────────────────────┤ │ Bonus: systematic-debugging（遇到 Bug 时触发） │ │ └── 四阶段根因分析：观察 → 假设 → 验证 → 修复 │ └─────────────────────────────────────────────────────────────────────────┘ ``` ### 各阶段产出物位置 | 阶段 | 技能 | 产出物 | 存储位置 | |------|------|--------|---------| | 规划 | brainstorming | 设计文档 | `docs/superpowers/specs/<日期>-<功能>-design.md` | | 规划 | writing-plans | 执行计划 | `docs/superpowers/plans/<日期>-<功能>.md` | | 执行 | TDD | 测试 + 实现代码 | 项目源码目录 | | 验证 | code-review | 审查记录 | PR / 审查工具 | | 完成 | verification | 验证报告 | 任务完成时声明 | --- ## 如何挂载到业务项目？ 本 Harness 采用 **"全局底座 + 项目专属上下文"** 的双层架构设计。请按照以下步骤将其引入你的业务项目： ### 第一步：挂载全局底座（Git Submodule） 在业务项目根目录下，执行以下命令将本仓库作为子模块引入： ```bash git submodule add <本仓库的Git URL> .harness ``` **版本管理建议**：Submodule 会锁定当前版本。当本仓库有规则更新时，业务项目需手动执行 `git submodule update --remote` 拉取最新规范，确保团队平滑过渡。 ### 第二步：创建项目入口文件 在业务项目根目录下创建 `AGENTS.md`，作为 AI 的自动识别入口。该文件是**轻量目录索引**，引用 `.harness/` 中的完整规则，避免重复： ```markdown # 项目 AI 上下文指南 ## 规则目录 - `.harness/rules/security.md` — 安全红线 - `.harness/rules/development-process.md` — 开发流程铁律（5 道 Hard-Gate） - `.harness/rules/java-coding-standards.md` — 编码规范 - `.harness/rules/java-architecture.md` — 架构规范 - `.harness/agents/coder.md` — 编码角色 - `.harness/agents/reviewer.md` — 评审角色 ## 技能目录（按阶段触发） - `.harness/skills/brainstorming/skill.md` — Phase 1: 需求澄清 - `.harness/skills/writing-plans/skill.md` — Phase 1: 任务拆解 - `.harness/skills/test-driven-development/skill.md` — Phase 2: 测试驱动 - `.harness/skills/systematic-debugging/skill.md` — Bonus: 调试方法论 - `.harness/skills/requesting-code-review/skill.md` — Phase 3: 审查请求 - `.harness/skills/verification-before-completion/skill.md` — Phase 3: 完成验证 ## 项目信息 - 技术栈：Spring Boot 2.0.7 + Java 8 - 常用命令：`mvn spring-boot:run`、`mvn test` ## 约束摘要 [粘贴高频红线，详见 AGENTS.md 模板] ``` ### 第三步：初始化 Superpowers 工作目录 在业务项目根目录下创建 Superpowers 工作目录，用于存放设计文档、执行计划和事件记录： ```bash mkdir -p docs/superpowers/specs docs/superpowers/plans docs/superpowers/incidents ``` 将这些目录加入 `.gitignore` 或纳入版本管理（取决于团队约定）： ```bash # .gitignore # 如果选择不纳入版本管理 docs/superpowers/ ``` ### 第四步：适配 AI 编程工具 | 工具 | 配置方式 | |------|---------| | **Qoder CN / 通义灵码** | 自动识别 `AGENTS.md`，无需额外配置 | | **Cursor** | 将 `AGENTS.md` 内容复制到 `.cursorrules` | | **Claude Code / Cline** | 自动识别 `AGENTS.md` | --- ## Harness 的日常维护与自进化 Harness 是一个"活系统"。为了让数字员工越来越聪明，请遵循以下维护原则： ### 1. 建立"错误驱动"的自进化闭环 当数字员工在业务项目中犯错（如幻觉、格式错误、越权操作、跳过 Gate）时，不要只在对话中纠正它： - **分析根因**：是缺乏上下文，还是规则不够明确？ - **更新规范**：将修复逻辑转化为明确的约束，提交 PR 更新本仓库的 `rules/` 或 `agents/` 文件。 - **全局生效**：让所有业务项目的数字员工"永远不再犯同类错误"。 ### 2. 将"软约束"升级为"硬校验" 自然语言的 Rule 终究是软约束。在维护 Harness 时，应逐步把高频、易错的规则沉淀为可执行的脚本（如配置 `pre-commit` 钩子、CI 流水线）。只有机器校验通过，任务才算真正完成。 **Superpowers 融合后的升级路径**： - 将 `rules/development-process.md` 中的 5 道 Hard-Gate 逐步转化为 CI/CD 流水线检查 - 例如：在 PR 模板中强制要求填写 "设计文档链接"、"计划文档链接"、"测试通过率" ### 3. 保持架构的"可拆卸"与弹性 随着底层大模型能力的提升，很多以前需要复杂 Pipeline 才能实现的功能，现在模型一个 Prompt 就能搞定。请定期审视 Harness 中的规则，及时移除冗余的控制逻辑，保持系统的轻盈。 **融合后的特别注意事项**： - Superpowers 的 skills 是可选的——业务项目可根据团队成熟度选择启用全部或部分技能 - 建议新团队启用全部 5 道 Gate，成熟团队可逐步放开部分 Gate - 定期检查 `docs/superpowers/` 目录的文档质量，及时归档过期的设计文档 --- ## 贡献指南 欢迎团队成员在日常开发中沉淀优秀的 SOP 或发现新的安全漏洞。 1. 从 `main` 分支拉取新分支（命名规范：`Feat_xxx`） 2. 修改或新增 `rules/`、`agents/`、`skills/` 下的文件 3. 提交 Pull Request，并在描述中说明 **"为什么需要这条新规则"**（最好附带踩坑案例） 4. 经过团队 Code Review 后合并 --- **核心理念：人类掌舵，AI 执行。用工程化的手段，驯服大模型的不确定性。**