# AI Native 手册（AI Native Handbook）

> AI Native 手册（AI Native Handbook）：用 Claude Code 做产品的实战手册，内容以 CC BY 4.0 开放。从小工具、产品到多仓库的组织协同，覆盖 AI-native 开发流程、工具链、护栏与 25 张真实踩坑卡片，并附带可安装的 Claude Code 插件。

- 网站：https://ainative.jubao.ai
- 全文：https://ainative.jubao.ai/llms-full.txt
- Claude Code 插件：`claude plugin marketplace add https://ainative.jubao.ai/marketplace.json` 然后 `claude plugin install ainative@ainative`
- 可信度标签：✅ 亲历（作者真实用过、有复盘）/ 🧪 试用中 / 📚 业界做法（未亲测）
- 许可：内容 CC BY 4.0，引用请注明出处与链接

## English summary

AI Native Handbook is a practical, experience-based guide to building products with Claude Code, written in Chinese by Neo (github.com/0xNeoTian), a founder who runs two organizations — a dozen repositories and dozens of agents — largely together with Claude Code. It distills 70+ real incident retrospectives into:

- a three-tier path: side tool → product (the six-stage AI-native SDLC: plan, design, build, test, ship, maintain) → organization (a separate ops repository, an org-level ops agent, layered memory, and feedback loops that keep rules alive);
- a hands-on comparison of the superpowers and Matt Pocock skills workflow plugins, and how to migrate between them;
- guardrails (permission rules, hooks, health checks) and 25 cards drawn from real retrospectives, each with a one-line rule;
- templates (one-page CLAUDE.md, intent, spec, plan, ADR, retro, REVIEW.md, subagent prompt);
- an installable Claude Code plugin (doctor, setup, recommend, new-project, pitfall-check, harvest).

Every page is labeled ✅ lived (used in production, backed by a retro), 🧪 trial, or 📚 industry practice (not yet verified by the author). An English edition is planned.

# AI Native 手册


- **入门**
- [开始](/docs): 这本手册写给谁、怎么读、从哪一档开始
- [为什么写这本手册](/docs/why): 一个人加 AI 运营两个组织，一年 70 多篇复盘之后的整理
- [选档：小工具、产品还是组织](/docs/tiers): 用三个信号判断项目处在哪一档，以及什么时候该升档
- [启动器](/docs/launcher): 选好档位，照着清单一步步起一个新项目，每一步都有可复制的命令

- **三档路径**
- 小工具篇
  - [小工具：30 分钟起步](/docs/tool): 一个人、一个仓库、没有长期用户：建仓、一页 CLAUDE.md、最小护栏、先出计划再动手，其余先不做
  - [小工具的最小护栏](/docs/tool/guardrails): 五条 deny 规则拦住最致命的误操作，再加三个习惯：密钥不进仓库、git 历史只由你动、定期确认规则还在
  - [小工具上线：静态站部署到 Cloudflare](/docs/tool/ship): 用 Workers 静态资源部署静态站：一份 wrangler.jsonc、一条部署命令，再绑定自己的域名
- 产品篇
  - [产品：AI-native 开发六阶段](/docs/product): 规划、设计、开发、测试、发布、运维：每个阶段留下什么产物、谁来把关、看哪个指标
  - [第 0 步：起步](/docs/product/day-0): 建仓库、写一页 CLAUDE.md、装流程引擎、配护栏：第一天花一小时，后面每次会话都省事
  - [规划：先写 intent](/docs/product/plan): 动手之前，先被拷问一轮，再用一页纸写清做什么、为什么、约束、不做什么和成功指标，由你确认
  - [设计：从 intent 到 spec](/docs/product/design): 一次会话里把 intent 拷问成可以开工的 spec，顺手留下术语表和 ADR；spec 以仓库里的文件为准
  - [开发：先出计划，再写代码](/docs/product/build): Plan mode 出计划，你批准后再实现；大功能拆工单，长任务分会话，实现类子 agent 不并行
  - [测试：让 Claude 能自己验证](/docs/product/test): 给 agent 一条能自己跑的反馈回路：一条命令验证、先写失败的测试、UI 改动亲眼看到，用证据判断完成
  - [发布：AI 审查，人来批准](/docs/product/ship): 审查三角（主力模型 → 异构模型 → 人）、整分支终审、发版清单，上线审批放在远端由人把关
  - [运维：线上问题变成新的 intent](/docs/product/maintain): 上线后盯住，出了问题先诊断再动手，把事故写成新的 intent 和复盘，再沉淀成会自动生效的规则
  - [选平台：Vercel 还是 Cloudflare](/docs/product/platform): Vercel 跑 Next.js 应用，Cloudflare 做底座：重叠在哪、各自强在哪，一个域名只挂一个平台
- 组织篇
  - [组织：什么时候需要 ops](/docs/org): 多仓库、多人协作之后，单靠每个仓库的 CLAUDE.md 不够用了
  - [ops 放哪：独立仓还是放进项目](/docs/org/ops-repo): 一句话判断标准，加上独立 ops 仓的三个代价和补法
  - [组织 ops agent 的五个组成部分](/docs/org/ops-agent): 身份、宪法、私人记忆、执行能力、进化回路，以及在 Claude Code 里怎么实现
  - [记忆分层：公开的、私人的、别再加新的](/docs/org/memory): 团队结论进 git，个人判断留私人记忆，不要让存储越来越多
  - [让 ops 和项目一起进化](/docs/org/evolve): 模板继承、园丁 agent、护栏体检：让复盘变成会自动生效的规则

- **专题**
- 流程引擎
  - [流程引擎、流水线与专项工具](/docs/workflow): 把工具分成三类，各自只让一个负责，避免抢触发
  - [superpowers 与 Matt：完整对比](/docs/workflow/superpowers-vs-matt): 自动注入流程 vs 手动调用 + 沉淀文档：用了一年 superpowers 之后为什么开始换
  - [从 superpowers 迁到 Matt](/docs/workflow/migrate): 逐个环节的对应关系、两套共存的配置，以及怎么用数据决定留谁
  - [gstack：上线流水线怎么用](/docs/workflow/gstack): 只用它最强的那几样：二审、安全审计、真实浏览器、发版
- 护栏与安全
  - [三层护栏](/docs/guardrails): 应用层、权限规则、hook 三层叠加，任何一层失效都还有兜底
  - [权限规则：deny、ask、allow](/docs/guardrails/permissions): 用 settings.json 把“绝对不行”和“必须确认”写进系统，而不是写进提示词
  - [用 hook 兜底](/docs/guardrails/hooks): PreToolUse hook 在危险命令执行前尽力备份一份，hookify 用一句话生成规则
  - [护栏体检：防止静默失效](/docs/guardrails/health-check): 护栏会被工具覆盖、被上游合并冲掉，所以要定期检查它们还在、还管用
  - [密钥与配置：别让工具覆盖你的设置](/docs/guardrails/secrets): 密钥只放环境变量或钥匙串，配置切换工具可能整份重写你的设置

- **资料**
- 坑库
  - [坑库](/docs/pitfalls): 每张卡片都来自真实复盘：发生了什么、为什么、怎么防
  - [跨仓链接用完整地址](/docs/pitfalls/absolute-cross-repo-links): 指向 ops 仓的相对链接，换到 worktree、GitHub 网页或云端 agent 就全断，而且不报错
  - [CI 绿了不等于能发版](/docs/pitfalls/ci-green-not-ready): 常年红着的检查会让人对红灯麻木，CI 本身也只覆盖一部分。防止拿 CI 状态代替发版前的全量验证
  - [跟代码绑定的文档跟代码放一起](/docs/pitfalls/code-coupled-docs): 恢复手册在 ops 仓里写着“Makefile 会先备份”，代码早被上游合并改掉，手册毫不知情
  - [切换工具会整份覆盖设置](/docs/pitfalls/config-overwrite): 用模型供应商切换工具切回官方后，权限规则、hook、插件启用状态全丢了，表面症状只是“插件都关了”
  - [自己审自己等于没审](/docs/pitfalls/cross-model-review): 主力模型自审时倾向于认同自己。防止把自审当成独立审查，用异构二审和人工批准补上
  - [本机代理会让 DNS 检查失真](/docs/pitfalls/dns-fake-ip): 本机代理的 fake-ip 模式劫持了 DNS 查询，dig 返回的全是假地址，差点误判部署失败
  - [不让 agent 动 git 历史](/docs/pitfalls/git-history-no-surgery): agent 为了“恢复状态”会自作主张 reset、rebase。用权限规则和提示词把改写历史留给人
  - [防护规则会悄悄失效](/docs/pitfalls/guardrails-decay): 护栏被上游合并冲掉、被工具整份覆盖时不会报错。用体检脚本和 CI 断言，让它失效时有人知道
  - [本地数据库也要按生产对待](/docs/pitfalls/local-db-is-prod): 本地库里攒着别处没有的配置和演示数据时，它就是生产。防止一条 reset 把它们清空且无从恢复
  - [“之前是这样的”先查 git](/docs/pitfalls/memory-vs-git): 人的记忆会把想过的设计当成做过的功能。防止 agent 把“以前有过”当约束，照着不存在的旧版去“恢复”
  - [一个域名只挂一个平台](/docs/pitfalls/one-domain-one-platform): 子域名同时挂在两个托管平台上，清理旧平台时差点连主域名一起删，殃及另一个还在服务的子域名
  - [同一时间只让一套流程自动接管](/docs/pitfalls/one-process-engine): 两套流程框架同时开着，一句“帮我 debug”会被不同框架抢走。只留一套自动触发，其余改成手动调用
  - [性能修复先问六个问题](/docs/pitfalls/perf-fix-six-questions): 性能修复最容易“看起来快了”就放行。上线前用六个问题查它有没有砍掉保护、改漏地方、没法观测
  - [插件不是越多越好](/docs/pitfalls/plugin-bloat): 装了 39 个插件、73 个 subagent，90 天里真正在用的只有十几个：按调用数据和常驻成本做减法
  - [实质改动先留文档再动手](/docs/pitfalls/process-before-code): 结果是对的，但 agent 直接改了代码、没留 spec 和 plan，事后没法审计、没法交接、没法请人 review
  - [对外内容先读权威文档](/docs/pitfalls/read-canonical-first): 凭记忆写的对外材料，细节容易和最新版本对不上。防止过时的说法进入长期对外的文档
  - [发版靠清单，不靠感觉](/docs/pitfalls/release-checklist): 发版由一组互相独立的动作组成，漏掉一步不会报错。防止“看起来发完了”其实少了一块
  - [亲眼看到才算完成](/docs/pitfalls/see-it-to-ship): 测试验证的是状态，用户看到的是渲染结果。防止“测试全绿、界面没变”就报告完成
  - [同一个组织的记忆不要按目录分裂](/docs/pitfalls/split-memory): 在父目录启动有 200 多条记忆，进子仓库只剩 8 条：自动记忆按启动位置分家，同一个坑反复踩
  - [计划和执行分开会话](/docs/pitfalls/split-plan-exec): 大任务在同一个会话里先计划后执行，计划会把上下文烧光。防止执行阶段带着残余上下文越做越差
  - [子 agent 别为省钱降级](/docs/pitfalls/subagent-strongest-model): 子 agent 降到小模型，单次看不出问题，累积下来跨字段不变量频繁被破坏，审查也兜不住
  - [临时方案要写明撤销条件](/docs/pitfalls/temp-fix-revert-trigger): 为赶发版加的临时绕路，事后没人记得撤，成了长期隐患。防止“临时”悄悄变成永久
  - [模板复制后会各自漂移](/docs/pitfalls/template-copy-drift): 第二个组织的规则文件复制自第一个，半年后 6 处引用指向不存在的文件，复审日期也过期半年
  - [网络报错先查远端](/docs/pitfalls/verify-remote-first): 超时和 503 只说明“结果未知”，不说明“失败”。防止盲目重试造成重复推送、重复打 tag
  - [分段审过了，还要整分支终审](/docs/pitfalls/whole-branch-review): 每个阶段单独审过，不代表合在一起没问题。防止跨阶段、跨文件的交互 bug 混进主干
- 模板
  - [模板库](/docs/templates): 直接复制使用的文档模板
  - [一页 CLAUDE.md](/docs/templates/claude-md): 只放每次都要遵守的规则：技术栈、命令、禁区和指针
  - [intent 模板](/docs/templates/intent): 做什么、为什么、约束、不做什么、成功指标
  - [spec 模板](/docs/templates/spec): 以 intent 开头的需求与设计规格，含验收标准
  - [plan 模板](/docs/templates/plan): 要改哪些文件、按什么顺序、怎么验证
  - [ADR 模板](/docs/templates/adr): 记录一个决策：背景、决定、后果、为什么没选别的
  - [复盘模板](/docs/templates/retro): 做了什么、为什么、遇到什么、下次怎么做，外加一节 Harness 反馈
  - [REVIEW.md 模板](/docs/templates/review): 写给 AI 审查者的规则：风险分级与谁有权批准
  - [子 agent 提示词模板](/docs/templates/subagent-prompt): 派子 agent 时提示词里必须有的七样东西
- 参考
  - [工具分工总表](/docs/reference/toolchain): 每件事由哪个工具负责，每个工具标了可信度和安装方式
  - [命令速查](/docs/reference/commands): 最常用的 Claude Code、插件、审查、部署与排障命令
  - [本手册的 Claude Code 插件](/docs/reference/plugin): 一条命令安装：体检、安装配置、推荐、新项目、坑检查、复盘提炼
  - [背后的理念](/docs/reference/ideas): 手册借用的五个外部理念：各自的核心主张、用在了哪些页面、原文在哪
  - [参考资料](/docs/reference/sources): 本手册引用的原始来源：方法论文章、Claude Code 官方文档、开源项目和平台文档
  - [更新日志](/docs/reference/changelog): 每个版本改了什么
  - [关于](/docs/reference/about): 作者、许可、写作标准与反馈方式