如果你已经在用 Claude Code 干活那你大概率经历过这样的场景同一个项目换个任务你得重新把技术栈、目录结构、代码风格交代一遍甚至同一个任务换个仓库又要从头对齐一次需求。用了一段时间之后我意识到这些问题不是工具能力不够而是我的工作方式太“临时”了——每次都在和 AI 进行一次性对话没有把可复用的部分沉淀下来。claude-code-templates 这个项目就是来解决这个问题的。它本质上是一套模板集合把项目启动、任务执行、代码审查、文档生成这些高频场景全部整理成了结构化提示词和工程配置。你可以把它理解成给 Claude Code 准备的一套“标准作业程序”每次开工前先跑一遍模板AI 就知道你是谁、在做什么项目、遵守什么规范、输出什么格式省掉大量重复沟通成本。这篇文章我会从模板集的设计思路讲起拆到目录结构、核心模板内容、实操配置再给出一份可以直接抄的快速上手指南和常见问题排查表。不管你是刚接触 Claude Code 的新手还是已经把它当成日常生产力工具的老手都可以从这里找到值得拿走的东西。1. 这个模板集到底在解决什么问题1.1 从“一次性对话”到“可复用工作流”Claude Code 本身的能力边界其实比大多数人想象的要宽。但真正卡住大家的往往不是模型能力而是每次对话都在“重新热身”。你想想看一个写惯了 Python 后端、平时用 FastAPI 和 PostgreSQL 的开发者和一个主攻前端、天天跟 React 和 TypeScript 打交道的开发者他们在同一个终端里启用 Claude Code 之后给出的第一条指令大概率是截然不同的。问题在于 AI 并不知道你的背景它只能根据当前对话里的只言片语去猜。这就导致一个很典型的现象前几轮对话基本都花在“对齐信息”上。你告诉它项目目录是 src/main/java它问你什么是核心业务逻辑你告诉它不要用 Lombok它在生成代码时还是忍不住给注解加上。这些反复拉扯不是模型的锅而是你缺少一个“启动协议”。模板集解决的就是这个启动协议的问题。它把每一次项目对话中那些永远不会变的背景信息、约束条件、输出格式预先写成标准文本。启动项目时加载一次后面所有对话都在这个上下文中运行不需要每轮重复。1.2 模板集的核心覆盖范围我整理的这套 claude-code-templates目前覆盖了五个主要方向项目启动模板定义技术栈、目录结构、代码风格、运行脚本让 AI 从第一秒就进入项目状态。任务执行模板把“实现一个功能”“修复一个 bug”“重构一段代码”这类常见请求规范成包含背景、约束、验收标准的完整提示词。代码审查模板固定审查维度比如安全性、性能、可维护性、边界条件给出结构化审查报告。文档生成模板统一 README、API 文档、变更日志的格式让 AI 根据代码自动产出规范文档。配置类模板CLAUDE.md、命令别名、自定义指令的模板让工具本身的工作方式也变得可控。每个方向都不是孤立存在的。一个完整的项目流程里启动模板负责“进入状态”任务模板负责“高效执行”审查模板负责“质量兜底”文档模板负责“沉淀输出”。它们组合在一起才构成一个完整的工作闭环。2. 模板集的设计思路与目录结构2.1 一套值得抄的目录组织方案先直接给出我这边整理后的目录结构你做一个整体感知claude-code-templates/ ├── README.md ├── templates/ │ ├── project-init/ │ │ ├── python-fastapi.md │ │ ├── node-nestjs.md │ │ └── react-frontend.md │ ├── tasks/ │ │ ├── fix-bug.md │ │ ├── add-feature.md │ │ └── refactor.md │ ├── review/ │ │ └── code-review.md │ ├── docs/ │ │ ├── readme.md │ │ └── api-doc.md │ └── config/ │ ├── CLAUDE.md │ └── commands.md ├── scripts/ │ └── apply-template.sh └── examples/ └── demo-project/一眼看上去这个目录的核心逻辑是按“使用场景”而不是“技术类型”分类。这是有意的设计。因为如果你按技术栈去分比如分成 Python 目录、Java 目录、前端目录那你会发现同一个技术栈下的任务模板还得再拆成“修 bug”“加功能”“做审查”目录层级会变得很深查找起来反而麻烦。按场景分类之后每个目录内部是同一类动作的不同变体使用路径会更短。2.2 模板设计的三条基本原则设计过程中我踩了不少坑最后总结出三条基本原则也可以说是血泪教训第一单一职责。一个模板只做一件事。不要搞出一个“万能模板”试图覆盖从启动到部署的全流程那只会让模板本身的篇幅失控最终你会发现 AI 在长文本里找不到重点。宁可多写几个小模板也不要写一个大而全的巨无霸。第二参数化。在所有需要变化的地方用占位符代替硬编码。比如项目名、端口号、语言版本、包名这些一律写成 {{PROJECT_NAME}} 或 {{PORT}} 这种形式。这样同一个模板可以复用到不同项目里而不是每次都要复制一份再手动改里面的细节。第三渐进式覆盖。模板不是一次性写死的。先覆盖最常见的高频场景比如“修 bug”和“加功能”然后在实际使用中不断把新的好案例沉淀进去。我的建议是第一版只放 5 到 6 个核心模板跑通几个真实项目之后再慢慢扩充。一上来就想做一套面面俱到的模板库结果往往是一堆永远不合身的衣服。3. 核心模板逐个拆解3.1 项目启动模板让 AI 进入状态这是整套模板里我使用频率最高的一个。每次开一个新项目或者切换到一个陌生的仓库我都会先加载对应的项目启动模板。它解决的是“AI 对这个项目一无所知”的问题。以 Python FastAPI 项目为例实际写好的模板大致长这样# 项目启动模板Python FastAPI ## 项目背景 - 项目名称{{PROJECT_NAME}} - 项目简介{{PROJECT_DESC}} - 技术栈Python 3.11、FastAPI、SQLAlchemy、PostgreSQL - 包管理Poetry ## 目录结构约定 - app/main.py 包含应用入口 - app/api/ 存放路由 - app/models/ 存放 ORM 模型 - app/schemas/ 存放 Pydantic 模型 - app/services/ 存放业务逻辑 - tests/ 存放测试用例 ## 代码风格要求 1. 使用类型注解 2. 遵循 PEP 8行宽 120 3. 所有业务逻辑放在 services 层不在路由里直接写 SQL 4. 不强制使用 Lombok如果涉及 Java这里改为不自动引入额外依赖 ## 常用命令 - 启动服务poetry run uvicorn app.main:app --reload - 运行测试poetry run pytest - 数据库迁移poetry run alembic upgrade head ## 约束条件 - 不要修改 requirements.txt使用 pyproject.toml 管理依赖 - 不要在项目中生成未使用的配置加载这个模板之后你再提“在这个项目里加一个用户登录接口”AI 就会自动套用 FastAPI 的惯例把文件放在 app/api/ 下面model、schema、service 分开写测试补在 tests/ 里。它不再需要问你“项目的目录结构是什么”因为你已经给了它一张地图。我见过很多人走到的误区是把一堆口头习惯随便写两行就当成模板。但模板的威力恰恰在于“具体”。你写“代码要整洁”没用写“所有业务逻辑必须放在 services 层不要在路由里写 SQL”才有约束力。越具体的约束AI 越容易遵守。3.2 任务模板把“帮我改一下”变成完整需求描述日常使用中我发现一个规律当你说“帮我把这个功能改一下”AI 的输出质量通常很平庸但当你说“帮我新增一个导出功能要求如下1、支持 CSV 格式2、默认只导出当前筛选后的数据3、文件大小超过 10MB 时拆分4、生成后返回下载链接”AI 的输出质量会明显上一个台阶。任务模板做的事情就是把这种“高质量描述”的格式固定下来。我常用的一个“新增功能”模板如下# 任务模板新增功能 ## 任务背景 - 所属项目{{PROJECT_NAME}} - 相关文件{{RELATED_FILES}} - 需求来源{{REQ_SOURCE}} ## 功能描述 {{FEATURE_DESC}} ## 验收标准 1. {{ACCEPTANCE_1}} 2. {{ACCEPTANCE_2}} 3. {{ACCEPTANCE_3}} ## 影响范围 - 是否涉及数据库变更{{DB_CHANGE}} - 是否涉及 API 变更{{API_CHANGE}} - 是否需要修改测试{{TEST_CHANGE}} ## 输出要求 1. 只输出本次变更涉及的代码文件不输出全项目代码 2. 给出关键改动点的逐行解释 3. 标注需要人工确认的风险点这套模板用下来的体会是“影响范围”这一项的价值被大多数人严重低估了。写清楚“是否涉及数据库变更”“是否涉及 API 变更”AI 就会主动去检查迁移脚本、检查接口版本兼容性而不是埋头生成完一堆代码就把尾巴丢给你。还有一种很常见的情况AI 在实现功能的时候把手伸到了不该碰的代码上。比如你只是想加一个接口它顺手帮你重构了工具函数。加了“只输出本次变更涉及的代码文件不输出全项目代码”这条约束之后这种蔓延现象明显减少。模板在这里起的作用其实是在帮 AI 界定工作边界。3.3 代码审查模板从“随便看看”到结构化检查代码审查是我认为最值得用模板固定下来的场景。因为人做审查很容易漏掉一些维度而 AI 做审查如果限制维度覆盖面可以做到非常稳定。我实战中的审查模板大致是# 代码审查模板 ## 审查范围 - 变更文件{{CHANGED_FILES}} - 变更分支{{BRANCH}} ## 审查维度 1. 功能正确性是否存在逻辑错误、边界条件漏洞 2. 安全性是否存在注入风险、敏感信息泄露 3. 性能是否存在明显的重复查询、大对象复制、阻塞调用 4. 可维护性命名是否清晰、函数是否过长、职责是否单一 5. 测试覆盖关键分支是否有对应测试 ## 输出格式 | 问题级别 | 文件位置 | 问题描述 | 改进建议 | |---------|---------|---------|---------| | 高 | xxx | ... | ... | | 中 | xxx | ... | ... | | 低 | xxx | ... | ... | ## 要求 - 按严重级别从高到低排序 - 只报告确凿的问题不要用“可能不够优雅”这类含糊表述 - 每条问题都给出可执行的修改建议模板中最核心的设计是“审查维度”的固定。很多人说 AI 做代码审查“不够深入”其实本质是提示词里没有指定审查维度。你只丢一句“帮我 review 一下代码”AI 只能凭感觉泛泛而谈。一旦你把安全性、性能、测试覆盖这些维度列出来它就会逐个维度去检查输出质量完全不一样。那个表格输出格式也很有用。一开始我让它用文字列问题反馈既乱又不好追踪。改成 Markdown 表格之后问题可以在项目管理系统里直接复制粘贴处理效率提升非常明显。3.4 文档模板让 AI 写出来的东西像人写的文档生成的模板比较特殊它不用占位符写满每个角落但也要规定整体结构和语气。这里我放一个 README 模板的核心框架# 项目名 {{PROJECT_NAME}}一句话说明项目做什么 ## 快速开始 - 环境要求 - 安装步骤 - 运行方式 ## 项目结构 - 核心目录职责 ## 常用命令 - 启动、测试、构建 ## 注意事项 - 已知坑点你会发现我刻意要求文档里出现“已知坑点”这一节而不是常见的“FAQ”或者“常见问题”。区别在于FAQ 往往是在凑内容而“已知坑点”是项目维护者真实踩过坑才会写的。这个细节让 AI 在生成文档时会去代码里搜索 TODO、FIXME、异常处理片段而不是套用模板里的空话。用 AI 生成文档最容易出现的毛病是“正确但无用”。它能正确描述每个文件是干什么的但通篇没有一个字是在真正指导新来的同事。模板里如果加上“基于代码注释和错误处理逻辑列出实际运行中可能遇到的问题”这一条输出的实用性会立刻拔高。4. 实操过程从克隆到产出第一个模板4.1 克隆项目并完成基础初始化先把这个模板集拉到你本地操作很简单git clone https://github.com/your-name/claude-code-templates.git cd claude-code-templates强烈不建议直接改模板仓库里原来的内容。我更习惯的用法是把所有模板复制到自己的项目目录下比如放到.claude-templates/目录在项目里就地维护。这样模板和项目代码保持在同一个仓库团队协作时其他人也能共享使用不需要每个人各自维护一份。如果你用的是类似思路可以在项目根目录创建一个快捷指令让 Claude Code 自动去加载模板。比如把下面这段写进项目的 CLAUDE.md启动新任务时先阅读 .claude-templates/tasks/ 目录下对应的任务模板并根据模板中的要求补充相关信息。4.2 参数化替换的实战操作模板里的占位符替换我推荐两种方式处理。第一种是手动替换。适合模板数量少、偶尔用一下的场景。你把{{PROJECT_NAME}}全量替换成order-service几秒钟就搞定了。第二种是写一个简单的脚本批量替换一套占位符。我这边用的是 node 脚本核心逻辑就几行#!/usr/bin/env bash # scripts/apply-template.sh TEMPLATE_FILE$1 PROJECT_NAME$2 OUTPUT_FILE$3 sed -e s/{{PROJECT_NAME}}/$PROJECT_NAME/g \ -e s/{{PORT}}/8080/g \ $TEMPLATE_FILE $OUTPUT_FILE echo 模板输出到 $OUTPUT_FILE这个脚本本身不难难的是想清楚哪些地方该参数化、哪些地方不该。我自己的经验是项目名、端口、语言版本、包管理工具这类信息适合参数化而代码风格约定、目录结构约定、约束条件这些内容是应该被固定下来的主干把它们参数化反而会让模板失去约束力。4.3 把实战经验沉淀回模板模板的维护跟写代码一样需要持续迭代。我在每次用完 Claude Code 之后都会花几分钟做一个动作如果这次对话里AI 给出过让我拍大腿叫好的输出或者反过来AI 给了我很离谱的输出我都会回头看一下是模板没写清楚哪条约束。举个例子。我之前做一次项目启动AI 全程没有按我项目里既定的“git commit 规范”提交代码每次生成的提交信息都很随意。后来我在启动模板里加了一行“提交信息格式type(scope): subjecttype 必须是 feat、fix、refactor、docs、test、chore 之一”。从那以后这个问题再没出现过。模板不是越厚越好而是越精准越好。每加一条规则之前先问自己这条规则是否能覆盖一类高频问题如果只是想给某个特别具体的场景兜底那不如直接在那一轮对话里说没必要写进模板污染公共配置。5. 常见问题与排查技巧实录5.1 模板不生效AI 还是我行我素这是最高频的问题。排查思路先分清是“没有加载”还是“加载了不遵守”。没有加载的表现是AI 对你的技术栈、目录结构完全没概念问出来的问题都很基础。这时候你应该检查 CLAUDE.md 里的引导指令是否写得足够明确尤其是那句“启动任务时先阅读模板”。加载了不遵守的表现是AI 明明知道规则但还是输出不符合规范的内容。这种情况常见于模板里的要求和对话里的指令冲突时AI 倾向于就近响应。我的解决方法是把约束条件放到模板靠前的位置并加上“这条约束优先于其他指令”的强调。有时候问题出在上下文被截断。Claude Code 的对话上下文长度是有限的项目启动模板如果太长跑到后面几轮对话时前面的规则可能已经被挤出窗口。这时候你需要做减法把模板压缩到不超过 200 行优先保留最硬性的约束。5.2 模板写得太空AI 发挥不稳定模板里充满了“代码要整洁”“性能要好”“注意安全”这类模糊表述就会出现发挥不稳定的问题。原因很简单AI 对“整洁”“好”“注意”这些词的理解和你不完全一致。改进的方向是把形容词改成可验证的规则。比如“代码要整洁”改为“函数内代码块不允许超过 80 行”“性能要好”改为“禁止在循环体内查询数据库”“注意安全”改为“所有 SQL 必须使用参数化查询禁止字符串拼接”越具体的规则AI 越没有自由发挥的空间输出也就越稳定。这一点怎么强调都不为过。5.3 模板文件太多AI 不知道用哪个模板多到一定程度会出现一个新的问题每次加载任务AI 要从一排模板里选一个但它经常选错。比如你让它“加一个功能”它跑去读了“项目启动模板”。我自己常用的解决办法是在 CLAUDE.md 里写一个简单的路由表## 模板选择指引 - 项目初始化、目录结构说明读取 .claude-templates/project-init/ - 新增功能、修复缺陷、重构读取 .claude-templates/tasks/ - 代码评审、质量检查读取 .claude-templates/review/相当于告诉 AI 什么场景读什么模板。这个简单的映射关系能让模板选错率降低一大截。5.4 模板被别人改坏了怎么追溯模板和代码一样存在协作维护问题。今天我加了一条规则明天同事改了一个占位符可能就把某个行为带偏了。这时候 Git 的可追溯性就派上用场了。我的建议是模板文件的每个更新都用一次单独的 commit并且 commit message 写清楚影响面。比如feat(template): 任务模板新增影响范围字段而不是update templates。这样一两个月之后回头看你能很清楚知道哪次改动影响了哪个模板。如果你发现某个模板越改越臃肿性能开始下降不要舍不得删。用git diff看最近几版改动把已经没用的部分砍掉保持模板的精简。6. 一些值得尝试的扩展方向6.1 按团队角色拆分配置模板除了按场景分还可以按角色分。比如架构师关注的模板是技术选型和项目初始化组长关注的是代码审查和变更影响一线开发关注的是任务执行和调试排错。每个角色不需要用全部模板只需要在 CLAUDE.md 里配上自己最相关的几个就能减少上下文的浪费。我实际试过的做法是在仓库的 docs 目录下维护一个ROLES.md里面定义不同角色对应的模板组合然后让 Claude Code 根据当前对话的目标自动决定加载哪一组。这个玩法比较适合团队统一推进 AI 工具使用规范的场景。6.2 结合版本控制做配置漂移管理模板库本身放在 Git 仓库里天然就有版本管理的能力。你可以给每个稳定的模板打一个 tag比如v1.0.0然后项目里的 CLAUDE.md 固定引用某个 tag 版本的模板避免模板在更新过程中给正在做的大型项目带来不必要的波动。这个思路参考了基础设施领域“配置漂移管理”的做法。用了一段时间后你会发现它对多人协作项目特别有价值因为不会出现“昨天模板还是好的今天怎么变了”的尴尬情况。6.3 把模板变成培训资料新同学入职与其手把手教他“我们项目怎么用 AI 辅助开发”不如直接丢一份模板库让他自己读。模板里的每一条规则都承载了一个踩坑故事读模板就是在读团队的开发规范。这一点是我个人最喜欢的用法。每次有新人问“你们项目里这个项目启动模板为什么这么写”我都能讲出一个真实的线上问题作为背景。模板因此不只是一堆约束它是团队工程文化的载体。我现在的个人习惯是每个新项目启用的第一周每天都会微调一次模板第二周开始就基本稳定下来之后就很少动了。如果你的模板需要频繁修改通常意味着你还没把问题想清楚先停下来分析一下为什么而不是急着往上堆规则。
claude-code-templates：Claude Code标准化提示词模板集
如果你已经在用 Claude Code 干活那你大概率经历过这样的场景同一个项目换个任务你得重新把技术栈、目录结构、代码风格交代一遍甚至同一个任务换个仓库又要从头对齐一次需求。用了一段时间之后我意识到这些问题不是工具能力不够而是我的工作方式太“临时”了——每次都在和 AI 进行一次性对话没有把可复用的部分沉淀下来。claude-code-templates 这个项目就是来解决这个问题的。它本质上是一套模板集合把项目启动、任务执行、代码审查、文档生成这些高频场景全部整理成了结构化提示词和工程配置。你可以把它理解成给 Claude Code 准备的一套“标准作业程序”每次开工前先跑一遍模板AI 就知道你是谁、在做什么项目、遵守什么规范、输出什么格式省掉大量重复沟通成本。这篇文章我会从模板集的设计思路讲起拆到目录结构、核心模板内容、实操配置再给出一份可以直接抄的快速上手指南和常见问题排查表。不管你是刚接触 Claude Code 的新手还是已经把它当成日常生产力工具的老手都可以从这里找到值得拿走的东西。1. 这个模板集到底在解决什么问题1.1 从“一次性对话”到“可复用工作流”Claude Code 本身的能力边界其实比大多数人想象的要宽。但真正卡住大家的往往不是模型能力而是每次对话都在“重新热身”。你想想看一个写惯了 Python 后端、平时用 FastAPI 和 PostgreSQL 的开发者和一个主攻前端、天天跟 React 和 TypeScript 打交道的开发者他们在同一个终端里启用 Claude Code 之后给出的第一条指令大概率是截然不同的。问题在于 AI 并不知道你的背景它只能根据当前对话里的只言片语去猜。这就导致一个很典型的现象前几轮对话基本都花在“对齐信息”上。你告诉它项目目录是 src/main/java它问你什么是核心业务逻辑你告诉它不要用 Lombok它在生成代码时还是忍不住给注解加上。这些反复拉扯不是模型的锅而是你缺少一个“启动协议”。模板集解决的就是这个启动协议的问题。它把每一次项目对话中那些永远不会变的背景信息、约束条件、输出格式预先写成标准文本。启动项目时加载一次后面所有对话都在这个上下文中运行不需要每轮重复。1.2 模板集的核心覆盖范围我整理的这套 claude-code-templates目前覆盖了五个主要方向项目启动模板定义技术栈、目录结构、代码风格、运行脚本让 AI 从第一秒就进入项目状态。任务执行模板把“实现一个功能”“修复一个 bug”“重构一段代码”这类常见请求规范成包含背景、约束、验收标准的完整提示词。代码审查模板固定审查维度比如安全性、性能、可维护性、边界条件给出结构化审查报告。文档生成模板统一 README、API 文档、变更日志的格式让 AI 根据代码自动产出规范文档。配置类模板CLAUDE.md、命令别名、自定义指令的模板让工具本身的工作方式也变得可控。每个方向都不是孤立存在的。一个完整的项目流程里启动模板负责“进入状态”任务模板负责“高效执行”审查模板负责“质量兜底”文档模板负责“沉淀输出”。它们组合在一起才构成一个完整的工作闭环。2. 模板集的设计思路与目录结构2.1 一套值得抄的目录组织方案先直接给出我这边整理后的目录结构你做一个整体感知claude-code-templates/ ├── README.md ├── templates/ │ ├── project-init/ │ │ ├── python-fastapi.md │ │ ├── node-nestjs.md │ │ └── react-frontend.md │ ├── tasks/ │ │ ├── fix-bug.md │ │ ├── add-feature.md │ │ └── refactor.md │ ├── review/ │ │ └── code-review.md │ ├── docs/ │ │ ├── readme.md │ │ └── api-doc.md │ └── config/ │ ├── CLAUDE.md │ └── commands.md ├── scripts/ │ └── apply-template.sh └── examples/ └── demo-project/一眼看上去这个目录的核心逻辑是按“使用场景”而不是“技术类型”分类。这是有意的设计。因为如果你按技术栈去分比如分成 Python 目录、Java 目录、前端目录那你会发现同一个技术栈下的任务模板还得再拆成“修 bug”“加功能”“做审查”目录层级会变得很深查找起来反而麻烦。按场景分类之后每个目录内部是同一类动作的不同变体使用路径会更短。2.2 模板设计的三条基本原则设计过程中我踩了不少坑最后总结出三条基本原则也可以说是血泪教训第一单一职责。一个模板只做一件事。不要搞出一个“万能模板”试图覆盖从启动到部署的全流程那只会让模板本身的篇幅失控最终你会发现 AI 在长文本里找不到重点。宁可多写几个小模板也不要写一个大而全的巨无霸。第二参数化。在所有需要变化的地方用占位符代替硬编码。比如项目名、端口号、语言版本、包名这些一律写成 {{PROJECT_NAME}} 或 {{PORT}} 这种形式。这样同一个模板可以复用到不同项目里而不是每次都要复制一份再手动改里面的细节。第三渐进式覆盖。模板不是一次性写死的。先覆盖最常见的高频场景比如“修 bug”和“加功能”然后在实际使用中不断把新的好案例沉淀进去。我的建议是第一版只放 5 到 6 个核心模板跑通几个真实项目之后再慢慢扩充。一上来就想做一套面面俱到的模板库结果往往是一堆永远不合身的衣服。3. 核心模板逐个拆解3.1 项目启动模板让 AI 进入状态这是整套模板里我使用频率最高的一个。每次开一个新项目或者切换到一个陌生的仓库我都会先加载对应的项目启动模板。它解决的是“AI 对这个项目一无所知”的问题。以 Python FastAPI 项目为例实际写好的模板大致长这样# 项目启动模板Python FastAPI ## 项目背景 - 项目名称{{PROJECT_NAME}} - 项目简介{{PROJECT_DESC}} - 技术栈Python 3.11、FastAPI、SQLAlchemy、PostgreSQL - 包管理Poetry ## 目录结构约定 - app/main.py 包含应用入口 - app/api/ 存放路由 - app/models/ 存放 ORM 模型 - app/schemas/ 存放 Pydantic 模型 - app/services/ 存放业务逻辑 - tests/ 存放测试用例 ## 代码风格要求 1. 使用类型注解 2. 遵循 PEP 8行宽 120 3. 所有业务逻辑放在 services 层不在路由里直接写 SQL 4. 不强制使用 Lombok如果涉及 Java这里改为不自动引入额外依赖 ## 常用命令 - 启动服务poetry run uvicorn app.main:app --reload - 运行测试poetry run pytest - 数据库迁移poetry run alembic upgrade head ## 约束条件 - 不要修改 requirements.txt使用 pyproject.toml 管理依赖 - 不要在项目中生成未使用的配置加载这个模板之后你再提“在这个项目里加一个用户登录接口”AI 就会自动套用 FastAPI 的惯例把文件放在 app/api/ 下面model、schema、service 分开写测试补在 tests/ 里。它不再需要问你“项目的目录结构是什么”因为你已经给了它一张地图。我见过很多人走到的误区是把一堆口头习惯随便写两行就当成模板。但模板的威力恰恰在于“具体”。你写“代码要整洁”没用写“所有业务逻辑必须放在 services 层不要在路由里写 SQL”才有约束力。越具体的约束AI 越容易遵守。3.2 任务模板把“帮我改一下”变成完整需求描述日常使用中我发现一个规律当你说“帮我把这个功能改一下”AI 的输出质量通常很平庸但当你说“帮我新增一个导出功能要求如下1、支持 CSV 格式2、默认只导出当前筛选后的数据3、文件大小超过 10MB 时拆分4、生成后返回下载链接”AI 的输出质量会明显上一个台阶。任务模板做的事情就是把这种“高质量描述”的格式固定下来。我常用的一个“新增功能”模板如下# 任务模板新增功能 ## 任务背景 - 所属项目{{PROJECT_NAME}} - 相关文件{{RELATED_FILES}} - 需求来源{{REQ_SOURCE}} ## 功能描述 {{FEATURE_DESC}} ## 验收标准 1. {{ACCEPTANCE_1}} 2. {{ACCEPTANCE_2}} 3. {{ACCEPTANCE_3}} ## 影响范围 - 是否涉及数据库变更{{DB_CHANGE}} - 是否涉及 API 变更{{API_CHANGE}} - 是否需要修改测试{{TEST_CHANGE}} ## 输出要求 1. 只输出本次变更涉及的代码文件不输出全项目代码 2. 给出关键改动点的逐行解释 3. 标注需要人工确认的风险点这套模板用下来的体会是“影响范围”这一项的价值被大多数人严重低估了。写清楚“是否涉及数据库变更”“是否涉及 API 变更”AI 就会主动去检查迁移脚本、检查接口版本兼容性而不是埋头生成完一堆代码就把尾巴丢给你。还有一种很常见的情况AI 在实现功能的时候把手伸到了不该碰的代码上。比如你只是想加一个接口它顺手帮你重构了工具函数。加了“只输出本次变更涉及的代码文件不输出全项目代码”这条约束之后这种蔓延现象明显减少。模板在这里起的作用其实是在帮 AI 界定工作边界。3.3 代码审查模板从“随便看看”到结构化检查代码审查是我认为最值得用模板固定下来的场景。因为人做审查很容易漏掉一些维度而 AI 做审查如果限制维度覆盖面可以做到非常稳定。我实战中的审查模板大致是# 代码审查模板 ## 审查范围 - 变更文件{{CHANGED_FILES}} - 变更分支{{BRANCH}} ## 审查维度 1. 功能正确性是否存在逻辑错误、边界条件漏洞 2. 安全性是否存在注入风险、敏感信息泄露 3. 性能是否存在明显的重复查询、大对象复制、阻塞调用 4. 可维护性命名是否清晰、函数是否过长、职责是否单一 5. 测试覆盖关键分支是否有对应测试 ## 输出格式 | 问题级别 | 文件位置 | 问题描述 | 改进建议 | |---------|---------|---------|---------| | 高 | xxx | ... | ... | | 中 | xxx | ... | ... | | 低 | xxx | ... | ... | ## 要求 - 按严重级别从高到低排序 - 只报告确凿的问题不要用“可能不够优雅”这类含糊表述 - 每条问题都给出可执行的修改建议模板中最核心的设计是“审查维度”的固定。很多人说 AI 做代码审查“不够深入”其实本质是提示词里没有指定审查维度。你只丢一句“帮我 review 一下代码”AI 只能凭感觉泛泛而谈。一旦你把安全性、性能、测试覆盖这些维度列出来它就会逐个维度去检查输出质量完全不一样。那个表格输出格式也很有用。一开始我让它用文字列问题反馈既乱又不好追踪。改成 Markdown 表格之后问题可以在项目管理系统里直接复制粘贴处理效率提升非常明显。3.4 文档模板让 AI 写出来的东西像人写的文档生成的模板比较特殊它不用占位符写满每个角落但也要规定整体结构和语气。这里我放一个 README 模板的核心框架# 项目名 {{PROJECT_NAME}}一句话说明项目做什么 ## 快速开始 - 环境要求 - 安装步骤 - 运行方式 ## 项目结构 - 核心目录职责 ## 常用命令 - 启动、测试、构建 ## 注意事项 - 已知坑点你会发现我刻意要求文档里出现“已知坑点”这一节而不是常见的“FAQ”或者“常见问题”。区别在于FAQ 往往是在凑内容而“已知坑点”是项目维护者真实踩过坑才会写的。这个细节让 AI 在生成文档时会去代码里搜索 TODO、FIXME、异常处理片段而不是套用模板里的空话。用 AI 生成文档最容易出现的毛病是“正确但无用”。它能正确描述每个文件是干什么的但通篇没有一个字是在真正指导新来的同事。模板里如果加上“基于代码注释和错误处理逻辑列出实际运行中可能遇到的问题”这一条输出的实用性会立刻拔高。4. 实操过程从克隆到产出第一个模板4.1 克隆项目并完成基础初始化先把这个模板集拉到你本地操作很简单git clone https://github.com/your-name/claude-code-templates.git cd claude-code-templates强烈不建议直接改模板仓库里原来的内容。我更习惯的用法是把所有模板复制到自己的项目目录下比如放到.claude-templates/目录在项目里就地维护。这样模板和项目代码保持在同一个仓库团队协作时其他人也能共享使用不需要每个人各自维护一份。如果你用的是类似思路可以在项目根目录创建一个快捷指令让 Claude Code 自动去加载模板。比如把下面这段写进项目的 CLAUDE.md启动新任务时先阅读 .claude-templates/tasks/ 目录下对应的任务模板并根据模板中的要求补充相关信息。4.2 参数化替换的实战操作模板里的占位符替换我推荐两种方式处理。第一种是手动替换。适合模板数量少、偶尔用一下的场景。你把{{PROJECT_NAME}}全量替换成order-service几秒钟就搞定了。第二种是写一个简单的脚本批量替换一套占位符。我这边用的是 node 脚本核心逻辑就几行#!/usr/bin/env bash # scripts/apply-template.sh TEMPLATE_FILE$1 PROJECT_NAME$2 OUTPUT_FILE$3 sed -e s/{{PROJECT_NAME}}/$PROJECT_NAME/g \ -e s/{{PORT}}/8080/g \ $TEMPLATE_FILE $OUTPUT_FILE echo 模板输出到 $OUTPUT_FILE这个脚本本身不难难的是想清楚哪些地方该参数化、哪些地方不该。我自己的经验是项目名、端口、语言版本、包管理工具这类信息适合参数化而代码风格约定、目录结构约定、约束条件这些内容是应该被固定下来的主干把它们参数化反而会让模板失去约束力。4.3 把实战经验沉淀回模板模板的维护跟写代码一样需要持续迭代。我在每次用完 Claude Code 之后都会花几分钟做一个动作如果这次对话里AI 给出过让我拍大腿叫好的输出或者反过来AI 给了我很离谱的输出我都会回头看一下是模板没写清楚哪条约束。举个例子。我之前做一次项目启动AI 全程没有按我项目里既定的“git commit 规范”提交代码每次生成的提交信息都很随意。后来我在启动模板里加了一行“提交信息格式type(scope): subjecttype 必须是 feat、fix、refactor、docs、test、chore 之一”。从那以后这个问题再没出现过。模板不是越厚越好而是越精准越好。每加一条规则之前先问自己这条规则是否能覆盖一类高频问题如果只是想给某个特别具体的场景兜底那不如直接在那一轮对话里说没必要写进模板污染公共配置。5. 常见问题与排查技巧实录5.1 模板不生效AI 还是我行我素这是最高频的问题。排查思路先分清是“没有加载”还是“加载了不遵守”。没有加载的表现是AI 对你的技术栈、目录结构完全没概念问出来的问题都很基础。这时候你应该检查 CLAUDE.md 里的引导指令是否写得足够明确尤其是那句“启动任务时先阅读模板”。加载了不遵守的表现是AI 明明知道规则但还是输出不符合规范的内容。这种情况常见于模板里的要求和对话里的指令冲突时AI 倾向于就近响应。我的解决方法是把约束条件放到模板靠前的位置并加上“这条约束优先于其他指令”的强调。有时候问题出在上下文被截断。Claude Code 的对话上下文长度是有限的项目启动模板如果太长跑到后面几轮对话时前面的规则可能已经被挤出窗口。这时候你需要做减法把模板压缩到不超过 200 行优先保留最硬性的约束。5.2 模板写得太空AI 发挥不稳定模板里充满了“代码要整洁”“性能要好”“注意安全”这类模糊表述就会出现发挥不稳定的问题。原因很简单AI 对“整洁”“好”“注意”这些词的理解和你不完全一致。改进的方向是把形容词改成可验证的规则。比如“代码要整洁”改为“函数内代码块不允许超过 80 行”“性能要好”改为“禁止在循环体内查询数据库”“注意安全”改为“所有 SQL 必须使用参数化查询禁止字符串拼接”越具体的规则AI 越没有自由发挥的空间输出也就越稳定。这一点怎么强调都不为过。5.3 模板文件太多AI 不知道用哪个模板多到一定程度会出现一个新的问题每次加载任务AI 要从一排模板里选一个但它经常选错。比如你让它“加一个功能”它跑去读了“项目启动模板”。我自己常用的解决办法是在 CLAUDE.md 里写一个简单的路由表## 模板选择指引 - 项目初始化、目录结构说明读取 .claude-templates/project-init/ - 新增功能、修复缺陷、重构读取 .claude-templates/tasks/ - 代码评审、质量检查读取 .claude-templates/review/相当于告诉 AI 什么场景读什么模板。这个简单的映射关系能让模板选错率降低一大截。5.4 模板被别人改坏了怎么追溯模板和代码一样存在协作维护问题。今天我加了一条规则明天同事改了一个占位符可能就把某个行为带偏了。这时候 Git 的可追溯性就派上用场了。我的建议是模板文件的每个更新都用一次单独的 commit并且 commit message 写清楚影响面。比如feat(template): 任务模板新增影响范围字段而不是update templates。这样一两个月之后回头看你能很清楚知道哪次改动影响了哪个模板。如果你发现某个模板越改越臃肿性能开始下降不要舍不得删。用git diff看最近几版改动把已经没用的部分砍掉保持模板的精简。6. 一些值得尝试的扩展方向6.1 按团队角色拆分配置模板除了按场景分还可以按角色分。比如架构师关注的模板是技术选型和项目初始化组长关注的是代码审查和变更影响一线开发关注的是任务执行和调试排错。每个角色不需要用全部模板只需要在 CLAUDE.md 里配上自己最相关的几个就能减少上下文的浪费。我实际试过的做法是在仓库的 docs 目录下维护一个ROLES.md里面定义不同角色对应的模板组合然后让 Claude Code 根据当前对话的目标自动决定加载哪一组。这个玩法比较适合团队统一推进 AI 工具使用规范的场景。6.2 结合版本控制做配置漂移管理模板库本身放在 Git 仓库里天然就有版本管理的能力。你可以给每个稳定的模板打一个 tag比如v1.0.0然后项目里的 CLAUDE.md 固定引用某个 tag 版本的模板避免模板在更新过程中给正在做的大型项目带来不必要的波动。这个思路参考了基础设施领域“配置漂移管理”的做法。用了一段时间后你会发现它对多人协作项目特别有价值因为不会出现“昨天模板还是好的今天怎么变了”的尴尬情况。6.3 把模板变成培训资料新同学入职与其手把手教他“我们项目怎么用 AI 辅助开发”不如直接丢一份模板库让他自己读。模板里的每一条规则都承载了一个踩坑故事读模板就是在读团队的开发规范。这一点是我个人最喜欢的用法。每次有新人问“你们项目里这个项目启动模板为什么这么写”我都能讲出一个真实的线上问题作为背景。模板因此不只是一堆约束它是团队工程文化的载体。我现在的个人习惯是每个新项目启用的第一周每天都会微调一次模板第二周开始就基本稳定下来之后就很少动了。如果你的模板需要频繁修改通常意味着你还没把问题想清楚先停下来分析一下为什么而不是急着往上堆规则。