🤖 Agent-Ready Project Template

A harness-first project starter that lets Claude, Codex, and other AI coding agents understand the repo from the README and take over development.

一个让任何 AI coding agent 在读完 README 后就能理解项目、进入工作流并接手开发的模板。

Keywords / 搜索关键词： Harness Engineering, Claude Code template, agent-ready repo, AI coding workflow, canonical docs, specs, contracts, verification, traces, Superpowers, GStack.

Tip

AI 在任何一台远程机器上，复制下面的 Egg Prompt，即可立刻搭建好完整的开发环境。
Give AI the "Egg Prompt" below on any remote machine — instant dev environment ready.

🌟 What an AI Can Do After Reading This Repo / AI 读完这个仓库后能做什么

🧠 理解项目结构与事实层：通过 AGENTS.md、CLAUDE.md 和 docs_canonical/
🧭 通过项目 intake 引导启动：先 /bootstrap-claude，再 /start-project
📝 澄清需求并生成 spec：通过 specs/ 与外部工作流命令
🚀 写实现计划并推进开发：/brainstorm → /write-plan → /execute-plan
🕵️ 做 code review、QA 和交付：/review → /qa → /ship
🛡️ 依据 contracts 和 verification 自检：参考 contracts/、verification/
📚 记录 traces 与失败经验：保留至 traces/、docs_canonical/LESSONS.md

如果你的目标是让 任何新的 AI coding agent 进入仓库后，不需要你手把手解释就能开始工作，这个模板就是围绕这个目标设计的。

📱 Supervise AI From Your Phone / 用手机当 AI 工头

这个模板也适合“AI 持续开发，你远程监工”的工作方式。你可以把它和远程工作流结合起来，通过 IM + OpenClaw 持续监督 Claude Code，或者用 Happy Coder 在手机上接管会话、查看进度、接收通知、追加任务。
This template also fits remote supervision workflows: you can combine it with IM + OpenClaw to monitor long-running Claude Code sessions, or use Happy Coder on your phone to check progress, receive alerts, and steer development from anywhere.

换句话说，它不只是一个“开始写代码”的模板，也适合 Claude Code 24h 持续开发、你随时远程干预 的工作流。

👉 24h 干活操作手册，直接喂给 Claude 即可：
https://ccn7vpu5l5y8.feishu.cn/wiki/PSPfwZPQ3ixAr4kxU4McIj64nYe?from=from_copylink

👥 Who This Is For / 这个模板适合谁

✅ 推荐人群 (Ideal For)

想让 Claude Code / Codex / AI agents 长期接手项目的人
想把项目从“只有代码”升级为 agent-ready repo 的团队
想把 spec、contracts、verification、traces 做成默认工程结构的开发者
想实践 Harness Engineering / Context Engineering 的独立开发者

❌ 不太适合 (Not Ideal If)

只需要一个纯 UI 脚手架
只需要一个仅负责生成页面的前端模板
不关心代码规范、验证机制、或可追溯性的快速 demo 仓库

✨ Why This Repo Is Different / 这个仓库和普通模板有什么不同

特性	❌ 普通项目模板	✅ 本模板 (Agent-Ready)
核心目标	重点是“开始写代码”	重点是“让 AI 长期接手开发”
文档管理	文档常常分散，容易过时	`docs_canonical/` 作为唯一事实层
需求追踪	需求大多停留在聊天记录	`specs/` 作为标准的任务入口
边界约定	接口和边界靠口头约定	`contracts/` 作为机器可验证契约
质量保证	做完功能后缺少证据	`verification/` 和 `traces/` 保留 review/QA 证据
工作流	容易随人变化	`Superpowers + GStack + 本地 hooks` 提供稳定流程

Important

The Core Promise / 核心承诺
把普通项目升级成一个 AI 在读完 README 后就能快速接手开发的 agent-ready repo。

🥚 Egg Prompt / 初始化提示词

Note

复制以下全部内容，丢给任何 AI（Claude Code / Cursor / Copilot 等）：
Copy everything below and paste to any AI (Claude Code / Cursor / Copilot):

我需要你帮我用阿东的模板初始化一个新项目：

1. 克隆模板仓库：
   git clone https://github.com/adongwanai/agent-ready-template.git
   cd agent-ready-template

2. 用官方初始化脚本创建新项目目录：
   ./scripts/init-project.sh ../my-project
   cd ../my-project

3. 安装 hooks（使其可执行）：
   chmod +x .claude/hooks/*.sh

4. 配置环境变量：
   如有需要，后续再按 Claude 的引导创建或补充 `.env`

5. 初始化 Git（如果是新项目）：
   git init
   git add .
   git commit -m "chore: init from agent-ready-template"

6. 打开 Claude Code 开始工作：
   claude

7. 进入 Claude Code 后，运行：
   /bootstrap-claude
   /start-project

8. 让 Claude 通过对话引导你：
   - 澄清项目目标、用户、需求和约束
   - 推荐合适的技术栈
   - 生成 README、canonical docs 和初版 spec
   - 决定是否保留 JS/TS 示例骨架

9. 只有在 Claude 明确确认使用 JS/TS scaffold 时，再执行：
   npm install

10. 然后按 Claude 的路由继续：
   /brainstorm → /write-plan → /execute-plan → /review → /qa → /ship

完成后告诉我：项目已初始化完毕，告诉我接下来要做什么。

📖 About This Repo / 仓库介绍

这是 阿东的 Claude Code 项目模板库，包含：

📦 核心内容	💡 详细说明
Harness-First 模板	语言无关的 harness 核心 + JS/TS 示例骨架
Canonical Docs	`docs_canonical/` 作为 agent 的事实层
Specs & Contracts	标准化的需求、契约、验证和证据目录
Skills 技能库	code-review、refactor、release、github-auto-pr
Hooks 自动化	原有 pre-edit / post-edit hooks 仍保留并接回设置
Agents 本地角色	pm-agent、coder-agent、reviewer-agent 仍保留
Codex Hooks	项目本地 trace/logging 能力会下发到新项目
GitHub Actions	PR 自动评分 + Issue → PR 自动化
双工作流	Superpowers (discovery/planning) + GStack (review/QA/ship)
组件拉取	`npx claude-code-templates@latest` 快速组装

🦞 My Harness Engineering Practice / 个人实践总结

这个仓库不仅仅是“模板”，更是对 Harness Engineering 的持续实践总结：

🔄 知识沉淀：把知识沉淀进 repo，而不是只留在人脑和聊天记录里。
🏗️ 固化结构：用 docs_canonical/ + specs/ + contracts/ + verification/ + traces/ 固化协作结构。
⚙️ 完整工作流：用 Superpowers + GStack + 本地 hooks/agents 形成闭环。
🧑‍💻 人类负责：spec、方向、验收、harness 演进。
🤖 AI 负责：澄清、规划、开发、review、QA、交付。

愿景：让一个全新的 AI coding agent 进入项目后就知道该读什么、该怎么做、该把证据放哪里、以及怎样长期稳定地演进项目。

⚙️ Core Workflow / 核心工作流

graph TD
    A([/bootstrap-claude<br/>安装并路由真实工作流]) --> B
    
    subgraph Superpowers [Discovery & Planning]
        B[<code>/brainstorm</code><br/>需求澄清] --> C[<code>/write-plan</code><br/>实施计划]
        C --> D[<code>/execute-plan</code><br/>按计划开发]
    end
    
    subgraph GStack [Review & QA & Ship]
        D --> E[<code>/review</code><br/>深度审查]
        E --> F[<code>/qa</code><br/>自动化测试]
        F --> G([<code>/ship</code><br/>发布])
    end

    classDef stage fill:#f9f9f9,stroke:#333,stroke-width:2px;
    class A,G stage;

🚀 Quick Start / 快速上手

选项一：AI 初始化（✨ 推荐）

把上面的 Egg Prompt 复制给 AI，5 分钟搞定一切。

选项二：手动命令

# 1. 克隆模板仓库
git clone https://github.com/adongwanai/agent-ready-template.git
cd agent-ready-template

# 2. 用官方初始化脚本创建真正的新项目目录
./scripts/init-project.sh ../my-project
cd ../my-project

# 3. 安装 Hooks
chmod +x .claude/hooks/*.sh

# 4. Git 初始化
git init
git add .
git commit -m "chore: init"

# 5. 启动 Claude Code
claude

进入 Claude Code 后，运行：

/bootstrap-claude
/start-project

等 Claude 帮你确认项目目标、技术栈和初版文档之后，如果确认使用 JS/TS 示例骨架，再执行：

npm install

选项三：GitHub Template

打开 agent-ready-template
点击 "Use this template" 按钮
填入项目名创建仓库，Clone 到本地并执行 chmod +x .claude/hooks/*.sh
打开 Claude Code，依次运行 /bootstrap-claude 和 /start-project
只有在 Claude 确认使用 JS/TS 示例骨架后，再执行 npm install

📁 Repo Structure / 仓库结构

agent-ready-template/
├── template/                    # ⭐ AI-First 项目模板（复制到新项目）
│   ├── AGENTS.md                # 跨 agent 入口
│   ├── CLAUDE.md                # AI 必读：项目核心指令
│   ├── README.md                # 模板说明
│   ├── docs_canonical/          # agent 的 canonical facts事实层
│   ├── specs/                   # 任务 spec存放地
│   ├── contracts/               # 机器可验证契约
│   ├── verification/            # review/qa/checklist验证清单
│   ├── traces/                  # trace、截图、视频、review 证据存放地
│   ├── .claude/                 # Claude Code 配置
│   │   ├── settings.json        # 自动启用 Superpowers
│   │   ├── commands/            # /bootstrap-claude 本地入口
│   │   ├── skills/              # 项目级补充技能
│   │   ├── hooks/               # 原有效 pre/post-edit hooks
│   │   └── agents/              # pm/coder/reviewer 子代理
│   ├── .codex/                  # Codex 本地 hooks / traces
│   ├── .github/workflows/       # GitHub Actions 自动化
│   └── docs/                    # 架构文档 + ADR
├── scripts/
│   └── init-project.sh          # 从 template/ 安全初始化新项目
└── README.md                    # 👈 你在这里

🧠 Harness Core / 核心心智模型

📂 Harness Core: docs_canonical/ · specs/ · contracts/ · verification/ · traces/
🌊 Workflow Layer: Superpowers + GStack
🛡️ Local Guardrails: .claude/hooks/ · .claude/agents/ · .codex/hooks/
🏗️ JS/TS Example Scaffold: package.json · tsconfig.json · ESLint · dependency-cruiser

(注：如需转为 Python / Go / Rust 等其他语言项目，只需保留 Harness core 并替换 Scaffold 部分即可)

🔧 Components / 组件拉取

# 查看可用组件
npx claude-code-templates@latest list

# 按需拉取模块
npx claude-code-templates@latest add auth        # 认证模块
npx claude-code-templates@latest add prisma      # 数据库模块
npx claude-code-templates@latest add e2e         # E2E 测试环境

🌐 GitHub Automation / GitHub 自动化

🔄 触发行为	🤖 自动执行动作
PR 加 `claude-review` label	AI 对 PR 自动评分（A/B/C/D/F）并给出改进建议
PR 中评论 `@claude`	自动代码审查并在 PR 下以总结形式回复
Issue 中 `@claude` + 需求	自动基于 issue 创建 branch 并提交 draft PR

🧪 Harness-Ready Audit Prompt / 审计你的项目

用以下提示词，让 AI 评估你的项目是否足够 harness-ready：

点击展开完整审计提示词 (Audit Prompt)

你现在是一位资深的 Harness Engineering 专家，熟悉 OpenAI 2026 年 2 月的官方 Harness Engineering 文章、LangChain 如何通过 harness 优化从 Terminal Bench Top30 跳到 Top5 的经验、以及 X 上工程师们讨论的 repo “harness-ready” 标准。

任务：评估我提供的代码仓库（或其描述）是否已经达到 “harness-ready” 状态，即适合交给 AI 编码代理长期、自主、高可靠地开发。

请严格按照以下 7 大维度打分并给出建议（每项 0-10 分）：
1. Context Engineering & Onboarding
2. Architectural Guardrails & Constraints
3. Verification & Feedback Loops
4. Tooling & Scaffolding
5. Spec & Task Engineering
6. Observability & Debuggability
7. Human-in-the-Loop Safety

输出格式（严格遵守）：
1. 总体 Readiness 分数：XX/100 → 等级
2. 每个维度的子项得分 + 简短解释
3. 优先级最高的前 5 条改进任务（带优先级）
4. 一句话总结：当前最缺的是什么部分？

现在请评估以下内容：
[在这里粘贴你的 repo 链接、或详细描述]

📚 Reference / 参考资料

👨‍💻 About the Author / 关于作者

阿东 (adongwanai) — 大模型算法工程师 & AI Agent 开发者

"AI handles the syntax. I focus on the product."
专注 Vibe Coding、Claude Skills、MCP 服务器开发。分享 AI 工作流与实战经验，帮助开发者提升 10x 编程效率。

🌐 个人主页: adongwanai.github.io
🐙 GitHub: @adongwanai
📕 小红书: 阿东玩AI的分享日常
📚 Vibe Coding 专栏: 获取 10x 编程心法与实战体系
✉️ 1:1 技术交流: contact@adong.ai (提供 AI 架构、Agent 落地顾问与培训)
💎 加入实战社区: 深入探讨 Agent 大模型的圈子

License: MIT — 自由商用、修改与分发。

Last updated: 2026-03

Name		Name	Last commit message	Last commit date
Latest commit History 11 Commits
!		!
.claude		.claude
.codex		.codex
.vscode		.vscode
agent-teams		agent-teams
best-practice		best-practice
changelog		changelog
development-workflows		development-workflows
docs/plans		docs/plans
implementation		implementation
orchestration-workflow		orchestration-workflow
presentation		presentation
reports		reports
scripts		scripts
template		template
tips		tips
videos		videos
.gitignore		.gitignore
.mcp.json		.mcp.json
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
a.svg		a.svg
c.svg		c.svg
s.svg		s.svg

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

🤖 Agent-Ready Project Template

🌟 What an AI Can Do After Reading This Repo / AI 读完这个仓库后能做什么

📱 Supervise AI From Your Phone / 用手机当 AI 工头

👥 Who This Is For / 这个模板适合谁

✅ 推荐人群 (Ideal For)

❌ 不太适合 (Not Ideal If)

✨ Why This Repo Is Different / 这个仓库和普通模板有什么不同

🥚 Egg Prompt / 初始化提示词

📖 About This Repo / 仓库介绍

🦞 My Harness Engineering Practice / 个人实践总结

⚙️ Core Workflow / 核心工作流

🚀 Quick Start / 快速上手

选项一：AI 初始化（✨ 推荐）

选项二：手动命令

选项三：GitHub Template

📁 Repo Structure / 仓库结构

🧠 Harness Core / 核心心智模型

🔧 Components / 组件拉取

🌐 GitHub Automation / GitHub 自动化

🧪 Harness-Ready Audit Prompt / 审计你的项目

📚 Reference / 参考资料

👨‍💻 About the Author / 关于作者

About

Uh oh!

Releases

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

🤖 Agent-Ready Project Template

🌟 What an AI Can Do After Reading This Repo / AI 读完这个仓库后能做什么

📱 Supervise AI From Your Phone / 用手机当 AI 工头

👥 Who This Is For / 这个模板适合谁

✅ 推荐人群 (Ideal For)

❌ 不太适合 (Not Ideal If)

✨ Why This Repo Is Different / 这个仓库和普通模板有什么不同

🥚 Egg Prompt / 初始化提示词

📖 About This Repo / 仓库介绍

🦞 My Harness Engineering Practice / 个人实践总结

⚙️ Core Workflow / 核心工作流

🚀 Quick Start / 快速上手

选项一：AI 初始化（✨ 推荐）

选项二：手动命令

选项三：GitHub Template

📁 Repo Structure / 仓库结构

🧠 Harness Core / 核心心智模型

🔧 Components / 组件拉取

🌐 GitHub Automation / GitHub 自动化

🧪 Harness-Ready Audit Prompt / 审计你的项目

📚 Reference / 参考资料

👨‍💻 About the Author / 关于作者

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Contributors

Uh oh!

Languages