Claude Code 的 7 个 CLAUDE.md 模板 | 可以直接复制到真实项目

很多 CLAUDE.md 教程只会说“写清楚技术栈”。这当然没错，但一旦 Claude Code 开始改真实项目，这种说明远远不够。

真正有用的问题不是“要不要写 CLAUDE.md”，而是：针对这个仓库，到底该写什么，才能让 Claude Code 不再重复同样的错误？

这篇文章用 7 个可复制模板，补上 新手入门指南 和 CLAUDE.md Best Practices 之间的空白。

最短路径：

1. 先把免费的 Claude Code Quick Reference Cheatsheet 放在手边。
2. 复制最接近你仓库的模板。
3. 先补 3 条 “Do Not” 规则，再补其他背景信息。
4. 如果你还想要更完整的模板、hooks、permissions 和配置示例，继续看 The Complete Claude Code Setup & Configuration Guide。
5. 如果你要把这件事推广到团队流程，直接走 consultation page。

好的 CLAUDE.md 实际在解决什么

它应该减少三类问题：

• 找对了文件，但没有遵守本地约定
• 做完修改，却跳过了你真正关心的验证步骤
• 因为仓库边界不清晰，Claude Code 探索了太多无关文件

所以一个实用文件通常至少包含：

• 技术栈和常用命令
• 目录结构说明
• 项目特有规则
• 推荐工作顺序
• 禁止事项

很多文章缺的恰好是最后两项。告诉 Claude Code 怎么做 和 不要做什么，效果提升最快。

模板 1：个人 Web 应用

# Project Overview

Customer-facing Astro site with a small Node API.

## Tech Stack

- Frontend: Astro 5 + TypeScript
- Styling: Tailwind CSS
- Backend: Node.js 22
- Tests: Vitest

## Key Directories

- `site/src/pages/` route entrypoints
- `site/src/components/` reusable UI
- `site/src/content/` blog and docs content
- `scripts/` operational scripts

## Common Commands

- Build: `cd site && npm run build`
- Test: `npm run test`
- Search content: `rg "keyword" site/src/content`

## Working Rules

- Prefer minimal diffs over wide refactors
- Keep copy changes aligned with existing brand tone
- When editing UI, verify mobile width before calling the task done

## Do Not

- Do not rename routes unless required
- Do not delete analytics or SEO fields
- Do not claim deploy success without checking the public URL

这里最重要的不是技术栈，而是把“移动端检查”和“公开 URL 检查”写成成功条件。

模板 2：带收入 CTA 的内容站

# Project Overview

Multilingual Claude Code content site with free PDF lead magnet, Gumroad products, and consultation funnel.

## Business Goal

- Priority 1: free PDF registration
- Priority 2: Gumroad product clicks and purchases
- Priority 3: consultation inquiries

## Content Rules

- Every new article must include internal links
- Every article must include free PDF, product, and consultation CTA paths
- Use the same slug across all locales when publishing multilingual posts

## Verification Workflow

1. Build the site
2. Deploy the site
3. Open the public URL
4. Check mobile layout
5. Confirm CTA destination links

## Do Not

- Do not publish only one locale when the article requires all locales
- Do not treat build success as release success
- Do not prioritize pageviews over conversion path quality

如果你的站点依赖文章、免费 PDF、Gumroad 产品和咨询转化，这种模板比普通工程模板更有用，因为它明确了收入路径优先级。

模板 3：后端 API 仓库

# Project Overview

Internal TypeScript API for billing and account management.

## Tech Stack

- Node.js 22
- Fastify
- PostgreSQL + Prisma
- Zod
- Vitest

## Directory Map

- `src/routes/` HTTP handlers
- `src/services/` business logic
- `src/repositories/` DB access
- `src/lib/` shared utilities

## Required Workflow

1. Read the route or service first
2. Check for existing schema and tests
3. Make the smallest safe change
4. Run unit tests or type checks
5. Summarize risk in plain English

## Do Not

- Do not bypass Zod validation
- Do not edit migrations casually
- Do not touch billing logic without tests

“Summarize risk in plain English” 这句很值钱。它会逼 Claude Code 解释影响，而不是假装每次修改都很普通。

模板 4：严格评审的团队仓库

# Team Workflow

- Work on the current branch only
- Do not revert changes you did not make
- Call out uncertainty before making broad edits
- Prefer review-friendly patches over large rewrites

## Pull Request Expectations

- Mention user-facing behavior changes
- Mention test coverage gaps
- Flag security, permissions, and deploy risks first

## Approval Boundaries

- Ask before deploy commands
- Ask before editing CI, infra, or secrets-related files
- Ask before changing lockfiles unless required

团队里最常见的问题不是“做得不够快”，而是“改动不好评审”。这个模板就是为了压低这种摩擦。

模板 5：遗留代码库

# Legacy Repo Notes

- This codebase has inconsistent patterns
- Prefer compatibility over elegance
- Preserve behavior unless the task explicitly allows change

## Investigation First

1. Explain current behavior
2. Locate the smallest responsible file set
3. Identify risks before editing

## Do Not

- Do not rename public methods casually
- Do not introduce new frameworks
- Do not rewrite files only to match modern style

在遗留仓库里，compatibility over elegance 往往是最值钱的一句。

模板 6：脚本和自动化仓库

# Automation Rules

- Dry-run whenever the script supports it
- Log intended side effects before executing
- Prefer idempotent operations
- Keep secrets out of logs and generated files

## Required Checks

- Confirm environment variables used
- Confirm target environment
- Confirm output path or destination service

## Do Not

- Do not send emails, deploy, or publish without explicit approval
- Do not delete generated assets unless cleanup is requested

如果仓库会触发部署、发邮件、写第三方 API，这类模板通常应该最先上。

模板 7：Monorepo

# Monorepo Map

- `apps/web/` customer app
- `apps/admin/` internal admin tool
- `packages/ui/` shared UI
- `packages/config/` lint and tsconfig presets

## Ownership Rules

- Web UI work should stay inside `apps/web/` unless the task clearly needs a shared component change
- Shared package edits require checking downstream usage
- Avoid version or config churn unless necessary

## Verification

- Run the narrowest relevant build or test command first
- Describe cross-package impact before editing shared code

Monorepo 最怕 Claude Code 过快跨包修改。先写清 ownership，效果通常立刻变好。

要避免的失败案例

失败 1：把 CLAUDE.md 写成公司 Wiki

长篇背景介绍会浪费上下文。短而可执行的规则更有用。

失败 2：只写命令，不写流程

npm run test 有用，但“改 billing 逻辑后必须跑测试”更有用。

失败 3：没有禁止规则

比如 “不要碰 .env”、“未验证公开 URL 不要说 deploy 成功”、“不要 force push”。这些句子往往最能挡事故。

失败 4：从不更新

如果 Claude Code 连续三次犯同一种错，通常不是模型问题，而是你的 CLAUDE.md 还不够具体。

怎么选模板

• 产品或 UI 工作为主：选个人应用模板
• 多语言文章、免费 PDF、Gumroad 漏斗：选内容站模板
• 更看重验证和数据正确性：选 API 模板
• 真正瓶颈是协作和边界：选团队或 Monorepo 模板
• 出错代价高：选遗留仓库或自动化模板

不需要把 7 个模板混成一个文件。先选最接近的一个，再加那些真正会改变行为的规则。

下一步

1. 复制一个模板到 CLAUDE.md
2. 增加 3 条项目专属的 Do Not
3. 写清楚“这个仓库里，什么叫完成”

如果你先想要一个日常速查表，拿免费的 Claude Code Quick Reference Cheatsheet。如果你想要更完整的 CLAUDE.md 模板、setup、hooks、permissions 和工作流例子，直接看 The Complete Claude Code Setup & Configuration Guide。如果你需要把这些模板落成团队标准流程，去 consultation page。