🤖 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 / 这个仓库和普通模板有什么不同

[!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 项目模板库，包含：

🦞 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

1. 打开 agent-ready-template
2. 点击 "Use this template" 按钮
3. 填入项目名创建仓库，Clone 到本地并执行 chmod +x .claude/hooks/*.sh
4. 打开 Claude Code，依次运行 /bootstrap-claude 和 /start-project
5. 只有在 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 自动化

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

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

你现在是一位资深的 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 / 参考资料

• 📖 Claude Code 官方文档
• 🛠️ Skills 官方市场
• 🚀 Superpowers 工作流
• ✅ GStack (审查/QA/Ship)
• 🧩 oh-my-claudecode
• 💡 Everything Claude Code (推荐阅读)

👨‍💻 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 大模型的圈子