renjianguojinqianfan/Project-Bootstrap-Harness

Project-Bootstrap-Harness (PBH)

一个为 AI 辅助编程设计的项目协议模板。

我们不教 AI 怎么思考，我们为它提供最佳的执行环境。

Python 3.11+
PyPI
License: MIT
zread

为什么需要这个？

用 Claude Code、Cursor 或 OpenCode 写代码时，你大概率遇到过这些摩擦：

- 每次新会话都要重新交代规则："记得跑测试"、"别改无关文件"、"先写计划再编码"
- AI 写了代码却不验证：小错误滚雪球，最后人类来兜底
- 切换 AI 工具时上下文断裂：Claude Code 理解的规则，Cursor 不知道

问题不在于 AI 不够聪明，而在于项目本身缺少一份"默认协作协议"。

PBH 在 harness-init my-project 的瞬间，把协议、质量门禁和状态记录种进项目。从此，任何打开这个项目的 AI 工具都能在 30 秒内知道：这里怎么跑测试、质量底线在哪里、当前项目处于什么阶段。

它是什么（以及不是什么）

✅ PBH 是

- 一份通用协作协议：AGENTS.md 作为所有 AI 工具的共同入口，定义致命规则、工作准则和项目结构
- 一套质量门禁基础设施：make verify 开箱即用，lint + 格式检查 + 测试 + 覆盖率一气呵成
- 一个可观测的 Agent 行为基准：同一份 AGENTS.md，你可以观察不同 AI 工具的遵循程度和表现差异
- 一个 Spec Coding 容器：提供 tasks/ 目录供你拆解任务，内容完全由你掌控
- 一个"协议的一次性播种器"：在项目创建时种下规则，让约束随项目走，不随人走。
- 一套生态协议标准：详见 docs/spec/PBH-SPEC.md — 定义了 AI 项目协作的通用规范，任何语言均可实现兼容工具。

❌ PBH 不是

- 不是 Agent 框架：不定义 AI 角色，不实现多智能体调度
- 不是代码生成器：不根据自然语言描述生成业务代码
- 不是 Spec Coding 流程工具：不生成 PRD、SPEC、constraints.md，只提供存放它们的目录

快速开始

pip install harness-init

完整模式（默认 CLI 模板）
harness-init my-awesome-project

选择项目类型
harness-init my-library --template=lib --yes
harness-init my-api --template=web --yes
harness-init my-analysis --template=notebook --yes

选择 IDE 配置（默认生成全部）
harness-init my-project --ide=cursor --yes    # 仅 Cursor
harness-init my-project --ide=none --yes      # 不生成 IDE 配置

快速模式（最小可用，5 分钟上手）
harness-init my-project --quick --yes

进入项目并验证：

cd my-awesome-project
pip install -e ".[dev]"
make verify        # 应输出 [OK] verified

💡 如果 make 命令不可用

Windows 用户可能未安装 make。若提示 'make' 不是内部或外部命令，你可以：

安装 make：

- Windows：安装 GnuWin32 Make 或运行 winget install GnuWin32.Make
- macOS：xcode-select --install
- Linux：sudo apt install make 或等价命令

或直接运行等价命令：

代码风格检查
ruff check src/ tests/

运行测试 + 覆盖率
pytest tests/ -v --cov=src --cov-fail-under=85

邀请 AI 入场：

"请阅读 AGENTS.md，了解这个项目的规则，然后帮我开始工作。"

生成的项目结构

my-awesome-project/
├── .harness/
│   ├── progress.json         # 项目阶段状态（AI 新会话的第一站）
│   └── workspaces/           # 多智能体工作区隔离（预留）
├── docs/
│   ├── context.md            # 深层上下文（架构、约定、任务）
│   └── decisions/            # 架构决策记录（ADR）
├── src/my_awesome_project/
│   └── cli.py                # CLI 入口（可按需替换）
├── tests/                    # 测试套件（镜像 src/ 结构）
├── tasks/                    # 任务拆解（Spec Coding 容器）
├── AGENTS.md                 # AI 协作协议（所有工具的共同入口）
├── Makefile                  # verify / test / lint / fix
├── pyproject.toml            # 依赖 + 工具配置
└── README.md

AGENTS.md：所有 AI 工具的共同入口

PBH 生成的核心文件是 AGENTS.md，它采用"机场导航"式结构，让 AI 在 30 秒内理解项目：

- 快速上手：第一步做什么、怎么跑验证
- 多智能体声明：支持多 AI 并行工作，建议使用独立 git worktree
- 工作准则：柔性引导——修改前先说明计划、聚焦原子任务、完成后验证
- 致命规则：不可违反的质量底线
- 安全指南：禁止硬编码密钥、命令审查等
- 文件映射：一目了然的目标速查

PBH 不定义 AI 角色，不强制特定工作流。它提供的是一个所有 AI 工具都能理解的通用协议。

两种模式对比

| 特性 | 完整模式 | 快速模式 (--quick) |
|------|----------|-------------------|
| AGENTS.md | 完整版（≤80 行） | 精简版（≤50 行） |
| CI/CD | ✅ GitHub Actions | ❌ |
| 文档体系 | ✅ context.md / ADR | ❌ |
| 依赖 | typer + pytest + ruff 等 | 仅 typer |

两种模式都包含：AGENTS.md、Makefile（verify/test/lint）、tests/ 目录、tasks/ 目录、progress.json。

适用场景

适合：

- 个人开发者使用多种 AI 工具，需要统一的项目级协作规则
- 小团队希望统一 AI 协作标准
- 需要可验证、可交接的 AI 辅助开发流程
- 想观察和比较不同 AI 工具在同一项目中的表现

不适合：

- 需要多智能体自主调度系统 → 使用专门的 Agent 框架
- 需要确定性自动化的无人值守流水线 → PBH 不锁死 Agent 行为
- 非 Python 项目 → 当前模板仅支持 Python 3.11+

路线图

- v1.1.0：砍掉越界功能，重写 AGENTS.md 为"机场导航"式，确立清晰边界
- v1.5.0 ✅：支持 --ide 参数（按需生成 IDE 适配文件）、--template 参数（cli/lib/web/notebook 多项目类型）、.harness/known_pitfalls.md
- v2.0.0 ✅：PBH-SPEC v2.0 协议标准发布、validate/doctor 合规性验证命令、正式宣告通用协议定位

本项目由个人业余维护，路线图按优先级动态调整。

生态

| 工具 | 说明 |
|------|------|
| Harness-Lint | PBH 生态的协议校验工具，覆盖 10 条 AI 代码缺陷规则，提供归因锚定报告 |
| Harness Agent | PBH 协议驱动的自主代码修复代理，形成发现→诊断→修复→审查→验证的完整闭环 |
| PBH-SPEC | AI 项目协作协议标准草案（中英文），欢迎社区参与讨论与实现 |

致谢

- Typer — 优雅的 CLI 框架
- Ruff — 极速 Python Linter
- Pytest — 可靠的测试框架

灵感来源：Anthropic 的 Agentic Workflow 与 Context Engineering 实践、OpenAI 的 Harness Engineering 理念与 Symphony 项目

License

MIT © renjianguojinqianfan