harness-init 1.0.0

CLI tool to initialize Harness Engineering projects

🚀 harness-init

为 AI Agent 准备的 Python 项目脚手架。 不是又一个代码生成器，而是一份任何 AI 工具都能读懂的 "协作合同"。

---

🤔 为什么需要这个工具？

用 Claude Code、Codex、Cursor 写代码时，你是否遇到过这些场景：

• AI 写了代码却不跑测试，小问题滚雪球？
• 新建一个会话后，AI 完全忘记之前的决策，需要你反复"喂"上下文？
• 团队里每个人对 AI 的指挥方式不一样，代码风格混乱？

问题不在于 AI 不够聪明，而在于我们没给它一个清晰、持久、可验证的"工作环境"。

harness-init 在创建项目的第一秒，就把 AI 的工作说明书、质量门禁和状态管理系统 种进项目里。从此，任何进入项目的 AI 工具都知道：该按什么流程干活、如何交接任务、以及怎样才算"做完了"。

---

✨ 核心特性

• 🤖 Agent 原生设计：生成的 AGENTS.md 定义了 Planner → Generator → Evaluator 三角色强制工作流，让 AI 学会"分工协作"。
• ✅ 生成即验证：内置 make verify 流水线，强制运行 ruff 代码检查 + pytest 测试，覆盖率门槛 ≥85%。质量不过关，项目不算生成成功。
• 🛡️ 约束即代码：自动提供 Git Hooks 脚本和 GitHub Actions CI 配置（可选），让规范成为不可绕过的硬约束。
• 📋 标准化的交接协议：计划模板、进度状态文件、交接摘要，让 AI 即使在新会话中也能"无缝接棒"。
• 🌍 双语文档：自动生成中英文 README.md，降低国际化团队的协作门槛。
• 🎯 专注 Python，刻意轻量：不实现复杂的 Agent 运行时，只做最擅长的事——定义一套通用的协作规范。

---

📦 安装

pip install harness-init

需要 Python 3.11 或更高版本。

---

🚀 快速开始

1. 创建新项目

harness-init my-awesome-project

按提示输入项目描述、作者信息（或使用 --yes 跳过）。

2. 进入项目并安装依赖

cd my-awesome-project
pip install -e ".[dev]"

3. 运行验证流水线

make verify

如果一切正常，你会看到 ✔ 验证通过。

4. 邀请 AI 入场

用 Claude Code、Cursor 或 Codex 打开项目，对 AI 说：

"请阅读 AGENTS.md，以 Planner 角色帮我规划一个功能：添加一个 CLI 命令来显示系统信息。"

AI 会自动读取工作流定义，按 计划 → 生成 → 评估 的节奏完成任务。

---

📁 生成的项目结构

my-awesome-project/
├── .harness/                 # Agent 工作区
│   ├── plans/                # 计划文件存放处
│   ├── state/                # 状态持久化
│   ├── templates/            # 计划模板等
│   ├── logs/                 # 运行日志
│   └── progress.json         # 任务进度追踪
├── configs/                  # 多环境配置
├── docs/                     # 文档（含 context.md 上下文）
├── src/my_awesome_project/   # 主包
│   ├── cli.py                # CLI 入口
│   ├── harness/              # 核心引擎（runner/evaluator/state/workflow）
│   ├── agents/               # Agent 骨架（planner/generator/evaluator）
│   ├── tools/                # 工具函数
│   └── utils/                # 通用辅助
├── tests/                    # 测试套件
├── .gitignore
├── AGENTS.md                 # AI 工作流强制说明书
├── opencode.yaml             # Codex 配置（含自定义命令）
├── Makefile                  # 验证与自动化任务
├── pyproject.toml            # 项目元数据与依赖
├── README.md                 # 中文说明
└── README.en.md              # 英文说明

---

🛠️ 命令选项

选项	简写	说明
--force	-f	强制覆盖已存在的目录（旧目录自动备份）
--no-git		跳过 Git 初始化
--yes	-y	跳过所有交互提示，使用默认值
--ci <platform>		生成 CI 配置文件（目前支持 github）
--version	-v	显示版本号

---

🗺️ 路线图

✅ 已完成 (v1.0.0)

• 计划模板从 Markdown 迁移到 JSON Schema（Breaking Change）
• 增强 AGENTS.md：审批工作流 + 安全规范（≤100 行）
• Git Hook 集成：.pre-commit-config.yaml + scripts/pre-push.sh|ps1
• GitHub Actions CI 配置：.github/workflows/ci.yml
• IDE 适配文件：CLAUDE.md、.cursorrules
• 项目文档：docs/PROJECT_MAP.md、docs/decisions/ADR_TEMPLATE.md
• 跨平台 .sh 执行权限自动修复

📅 计划中

• 探索多技术栈支持（Node.js / Go）
• harnessctl CLI 增强

⏰ 本项目由个人业余维护，路线图不承诺具体发布时间，按功能优先级和社区反馈动态调整。

---

📅 维护节奏

• 🐛 Bug 修复：通常在一周内响应。
• ✨ 新功能：每 2-4 周 发布一个小版本，按路线图推进。
• 💬 Issue 回复：尽量在 48 小时内回复。

感谢你的耐心和理解！欢迎通过 Issues 和 Discussions 参与讨论。

---

🤝 贡献

欢迎任何形式的贡献！请阅读 CONTRIBUTING.md 了解开发规范和提交流程。

---

📄 许可证

MIT License © renjianguojinqianfan

---

🙏 致谢

• Typer - 优雅的 CLI 框架
• Ruff - 极速 Python Linter
• Pytest - 可靠的测试框架
• 灵感来源：Anthropic 的 GAN 式三智能体架构、OpenAI 的"代码仓库作为记录系统"实践、Martin Fowler 的 Harness Engineering 论述。

---

English Version