AI 编程实战：用可复用模板为 Claude Code 建立项目工作协议

做开发这行身边已经有不少同事从网页版聊天窗搬到了终端里的 Claude Code。用了一阵子你会发现这类工具真正拉开体验差距的往往不是模型有多聪明而是你有没有给它一份靠谱的“工作协议”——也就是项目根目录里那个 CLAUDE.md。我开始整理 claude-code-templates 这个模板库就是因为新项目开得太频繁每次都要重新交代技术栈、代码规范、测试习惯会话一多就很烦。这个项目目前的形态是一套面向不同研发场景的 Claude Code 配置模板包含 CLAUDE.md、自定义命令slash command、hooks 校验脚本和一批示例。适用范围覆盖 Web 前端、Python 后端、数据处理脚本、DevOps 自动化等常见工作流。如果你刚接触 Claude Code想在上手第一天就有一份像样的项目配置或者你已经在用但总觉得 AI 输出的代码风格飘忽不定这套模板可以直接拿来改一改也可以当作一份“怎么写好 CLAUDE.md”的参考手册来看。1. 这个项目到底在解决什么问题1.1 Claude Code 的“工作协议”为什么重要Claude Code 和普通聊天窗最大的不同是它占有了整个仓库的上下文——能读文件、跑命令、查 git 历史然后直接在终端里修改代码。它每次会话启动时会自动加载项目根目录下的 CLAUDE.md把它作为行为的“默认准则”注入整个对话。很多人的 CLAUDE.md 长这样这是一个 Node.js 项目使用 TypeScript。写完这句就开干。结果呢模型每次都能理解项目背景但输出的代码风格还是很随机有时候用函数式写法有时候用 class有时候给异常加了详细处理有时候遇到 get 请求直接 throw。因为你的“工作协议”里只写了“是什么”没写“怎么做”。我自己把 CLAUDE.md 理解成新员工入职手册。手册里如果只写“我们公司做电商”新员工依然不知道代码规范、提交流程和验收标准。真正有价值的手册应该明确告诉对方什么场景下做什么决策、哪些事绝对不要做、常用命令有哪些、提交前要跑什么检查。Claude Code 也是同样的逻辑你给它多少约束它就还你多少稳定。1.2 模板库解决的核心问题清单claude-code-templates 这个项目最初就是为了消灭三件事重复劳动。新项目从零写一份好用的 CLAUDE.md 至少要半小时而复制模板改参数只要两分钟。经验流失。项目团队好不容易磨合出来的约定比如“后端接口必须有 zod 校验”“前端组件必须写测试”全存在老成员的脑子里换个人就没了。把它们写进模板等于把团队记忆版本化。上下文字面膨胀。很多人把 CLAUDE.md 越写越长恨不能塞进整个团队的 wiki。这会让每次请求的 token 消耗大幅上涨而且重点被稀释。模板的作用是帮你控制“密度”只留下高频、强制、容易出错的规则。这套模板不是给你“抄作业”的它给的是一个经过验证的基线。你拿到之后改吧改吧就能用至少比自己从零开始琢磨要靠谱得多。2. 模板库的整体设计与分层复用2.1 目录结构按研发场景分库项目结构长这样我先贴出来再解释claude-code-templates/ ├── CLAUDE.md # 模板库自身使用的编写规范 ├── templates/ │ ├── web-frontend/ │ │ ├── CLAUDE.md │ │ ├── commands/ │ │ │ ├── review.md │ │ │ ├── test.md │ │ │ └── fix-lint.md │ │ ├── hooks/ │ │ │ └── check-debugger.mjs │ │ └── examples/ │ │ └── hmr-demo │ ├── python-backend/ │ │ ├── CLAUDE.md │ │ ├── commands/ │ │ └── hooks/ │ ├──>## 必填参数 PROJECT_NAME: 项目名英文短横线 PACKAGE_MANAGER: pnpm / npm / yarn TEST_FRAMEWORK: vitest / jest INTERNAL_REGISTRY: 是否使用公司私有 npm 源然后在CLAUDE.md模板里用{{PROJECT_NAME}}这类占位符标记需要替换的位置。scripts 目录下那个gen-project.sh会读取你的输入用 sed 批量替换占位符同时把TEMPLATE_VARS.md改名为CLAUDE.md放入新项目目录。这样手动操作也能做但脚本能帮你避免漏改、错改。3. 核心模板实例拆解三个可直接对照的配置3.1 Web 前端管理模板一个小而完整的例子Web 前端模板是我最常用的一个内容刻意控制在 50 行以内。给你看一段节选# Project: {{PROJECT_NAME}} ## Stack - Framework: React 18 Vite - Language: TypeScript (strict) - Styling: Tailwind CSS, do not introduce component libraries unless necessary ## Workflow 1. When starting a feature, read src/features/ to understand existing patterns 2. After modifying a component, run npm run lint --fix before committing 3. API calls must be wrapped in src/lib/api.ts; do not spread fetch calls across pages 4. Unit tests use Vitest; cover new hooks with at least one test ## Do Not - Do not modify public/ files without explicit request - Do not use any pinyin in file names; use English kebab-case有几个细节值得展开说。第一指令全部用“When... do...”句式而不是单纯的祈使句。给模型设了一个触发条件它更容易判断“什么时候需要执行这条规则”。第二明确列出 Do Not 清单尤其是那些容易引发事故的行为比如改public/下的静态资源。第三用“do not introduce component libraries unless necessary”这种带判断的措辞避免它遇到一点小需求就给你引入一个新依赖。这套模板实测下来有个明显效果新功能开发时模型基本不会主动去改和需求无关的文件代码风格也会趋向统一因为它每改一个组件都会先看同目录其他组件的写法。3.2 Python 后端模板先管依赖再管结构Python 后端模板的核心关注点不太一样它更强调依赖管理、日志和异常处理的统一规范# Project: {{PROJECT_NAME}} ## Stack - Python 3.12 FastAPI - Dependency management: poetry (do not use pip install) - Database migration: alembic (never commit .db files) ## Code Rules 1. Handlers must not contain business logic; logic goes to services/ 2. All API responses follow schemas/common.py envelope 3. Logger must use logging.getLogger(__name__), not print() 4. When adding new dependencies, update pyproject.toml and lock file together这条模板解决的痛点很实际Python 项目最不缺的就是乱装的依赖。模型有时候为了解决一个小问题给你pip install一个新的包还不更新 lock 文件。有了“dependency management: poetry (do not use pip install)”这条硬约束再配合 hooks 里检查 lock 文件变更的脚本这类问题基本被卡死。日志规范也值得写进模板。模型默认会用各种方式输出日志有的写 print有的用 third-party 库。把它们统一到标准库 getLogger 之后后续排查生产问题会少很多烦心事。3.3 数据处理与脚本类模板面向“一次性任务”的约束数据处理脚本和 Web 应用完全不是一回事。这类任务写的代码往往是一次性的跑完就扔但它一旦出错重跑成本可能以小时计。所以模板里会特别强调幂等性和断点续跑# Project: {{PROJECT_NAME}} ## Mode - This is a data pipeline; idempotency is the top priority - Every step must be resumable from checkpoint; never re-run raw ingestion if partial results exist ## Conventions 1. Pipeline steps live in steps/ with two files each: run.py and checkpoint.sql 2. Every table write must be idempotent (upsert key on natural key) 3. Sensitive data fields must be masked before logging 4. Add a --dry-run flag to every CLI entry point模板里那句“Every step must be resumable from checkpoint”看起来很苛刻但它拯救过我好几次。数据管道跑了一半网络断了如果前面步骤不可重入整个任务就得从头开始。把这些约定写进 CLAUDE.md模型在生成新管道时会默认遵守而不是等出了问题再来修。3.4 模板如何接进 Claude Code拿到模板之后接入方式很简单把对应场景的CLAUDE.md内容复制到项目根目录。如果有自定义commands/放到项目下的.claude/commands/目录。如果有hooks/脚本放到项目下的.claude/hooks/同时在.claude/settings.json里注册。重启 Claude Code 会话让它重新加载配置。我一般在接完模板后的第一句话会主动确认一次“请阅读 CLAUDE.md 并总结项目的开发规范。”这样做的好处是让模型在会话开始阶段就把规范“拿出来”亮了亮相后面执行时会明显更贴合。新版本的 Claude Code 还支持 /init 命令可以自动生成一个初步的 CLAUDE.md但那个生成结果比较泛只能当骨架本项目的模板才是填好的血肉。4. 从零搭一套自己的模板实操全流程4.1 先把隐性约定写成白纸黑字很多人问我“我的团队没什么约定怎么写模板”其实每一段真实项目里都有约定只是散落在 review、commit 和聊天记录里。我的做法是四个来源收集翻最近 50 条 commit看哪些文件总被一起改动那往往是某种约定在起作用。翻 code review 里被挑出的高频问题比如“这个错误没被处理”“日志格式不对”把它们转成规则。统计最常用的命令比如pnpm lint:fix、python manage.py test写进 Workflow。找一份内部 dev wiki 或者 README 的 FAQ看哪些问题是新员工反复问的。第一次整理不用求全先挑 10 条最重要的。规则太多会稀释模型的注意力而且你很难判断是哪条规则在执行出了问题不好排查。4.2 用斜杠命令包住高频任务CLAUDE.md 适合放“常驻规则”而复杂操作更适合做成自定义命令。比如代码审查这个动作如果不用命令你得每次打一长段 prompt“请分析当前 diff 的问题关注命名、性能、边界条件、测试覆盖”。有了/review命令一切都封装好了--- description: Review the current diff for correctness argument-hint: [optional scope] --- You are a senior reviewer. Read the current diff with git diff {{scope}}, focus on: naming quality, performance traps, missing edge cases, incomplete tests. Write feedback as a sorted list: critical / warning / suggestion.我在这套模板库里放了五个高频命令/review、/test生成测试用例、/fix-lint自动修 lint、/onboard自我介绍项目背景、/explain讲解一段代码的上下文。其中/onboard对新会话尤其有用它会让模型重新读取一次 CLAUDE.md 和相关文档相当于手动刷新工作协议。4.3 用 hooks 卡住危险操作有些规则光靠“告诉模型”不够因为你没法确定它每一轮都严格遵守。这时候就要上 hooks从程序层面拦截。比如我在 Web 前端模板里加了一个检查 debugger 的钩子{ hooks: [ { matcher: Edit, hooks: [ { type: PreToolUse, command: node .claude/hooks/check-debugger.mjs } ] } ] }对应脚本做的事情很简单扫描将要修改的文件如果发现debugger关键字输出非零退出码Claude Code 就会自动中止这次修改并要求开发者处理后再继续。这里有个小经验hooks 脚本的职责越单一越好别写一个几百行的万能检查器维护跟不上最后只会变成摆设。4.4 把模板验证变成可重复的测试模板不是写出来就算完它得证明自己真的有效。我在 scripts 里写了一个test-template.sh做的事很粗暴但有效为每个场景准备两个测试仓库一个套模板一个不套然后让 Claude Code 执行同样的功能开发任务最后对比结果。我实测过一轮“给列表页加排序和筛选功能”的任务结论很有意思用了模板的仓库一次通过的代码评审没有出现“直接修改未相关文件”的情况函数命名也匹配了项目既有习惯没模板的仓库功能能跑但改动了路由配置和公共样式文件还引入了一个不必要的状态管理库。这种偏差在单次任务里不致命但累积起来就是项目优雅和糟糕的分界线。5. 常见问题与排查技巧实录5.1 CLAUDE.md 太长上下文装不下症状很明显会话进行到一半发现模型的决策开始“失忆”明明模板里写了的事又开始违规。最典型的元凶就是模板里塞了太多低频内容。解决思路是分级存放。CLAUDE.md 只保留高频强规则详细规范放到 docs 里让模型在需要时自己打开查阅。比如模板里写“Database migrations followdocs/db-migration.md”这行字占的 token 极少但它把详细文档的访问路径给了模型。实测下来长会话里的违规率明显下降。如果某些文件必须常驻也可以研究下你所用版本的import和附加加载机制但我的原则还是常驻内容越少越好。5.2 指令冲突与优先级不明模板多了之后会出现一个尴尬情况CLAUDE.md 说“用 poetry 管理依赖”某个 slash command 里又写了pip install。模型碰到这种矛盾行为会变得随机有时听这个、有时听那个。我在模板库的公共约定里加了一条优先级规则“CLAUDE.md 是所有指令的最高优先级命令和 hooks 不得与其冲突。若存在冲突以 CLAUDE.md 为准。”同时在每个模板的头部都保留一个“Highest Priority”栏目把最重要的两三条约束放进去。这样一旦发生冲突模型至少有明确的裁决依据。日常维护中我每隔一段时间还会搜一遍 templates 目录看有没有新引入的命令和根规则相抵触。5.3 模板陈旧、与项目脱节拿前端模板举例我在 Vite 4 时代写的约定到了 Vite 6 项目上照样会生效但那套“npm run dev 启动开发服务”的流程描述对新项目的 dev script 未必还适用。模板的保质期客观存在偷懒不维护它只会从助手的经验书变成误导手册。我现在给每个模板都加了一个元信息头--- template: web-frontend version: 2.4.0 last_updated: 2026-01-10 based_on: Vite 6 React 18 ---同时用 git log 追踪修改记录每隔两三个月批量审查一轮。审查方式很简单拿着模板去套一个真实的新项目看有没有不和谐的地方。那些“看起来没问题但实际没人会按它执行”的规则我会直接删掉。5.4 团队不买单模板推不下去工具链再顺手如果团队成员感受不到价值最终也是废弃。我在公司内部推广模板时碰到过一个典型障碍老同事觉得多了一个文件碍事新同事觉得规则太死。后来我调整了策略不在第一天把 50 条规则全塞进去而是只放最重要的 5 条让团队先跑起来。等有人发现“AI 开始遵守我们约定的提交前缀了”“新代码的命名风格统一了”再逐步放开更多规则。这个“先小步见效再慢慢扩展”的思路放在任何团队里都比一次推全量有效。6. 一点真实体会用上这套模板库之后最直观的变化不是模型变聪明了而是“不需要重复教它常识”了。以前一个新项目要花半天时间磨合让它理解我们的目录习惯、测试要求、提交规范现在新仓库拉下来把 CLAUDE.md 放进去它就是那个“熟悉本地规矩的老同事”。如果让我给刚接触 Claude Code 模板的人一个建议我会说先去模板库里挑一份最贴近当前项目的配置照着改成自己的然后跑两个真实任务试试。别一上来就追求完美规则先用起来哪里痒痒改哪里两个迭代周期之后你会对“什么值得写进模板”产生完全不同的理解。等到熟悉了自己的写法再回来看这套模板你大概也能给自己的项目写一套专属定制的规范了。