跳到主要内容

CLAUDE.md 起步模板

所有级别

CLAUDE.md 是你能给 Claude Code 的最高杠杆的东西：它是 Claude 每次会话都会读取的持久化指令。把下面任意一个模板放到你的仓库根目录（或运行 /init 生成一个起点），然后裁剪到合适。用每个代码块上的复制按钮即可。

:::tip 保持简短而真实 一个冗长、空想或过时的 CLAUDE.md 会帮倒忙 —— Claude 会照字面执行它。请描述项目实际的运作方式，并狠心删减。详情见 CLAUDE.md 页面。 :::

通用起步模板​

# Project: <name>

## What this is
<One or two sentences: what the project does and who uses it.>

## Tech stack
- Language/runtime: <e.g. TypeScript, Node 20>
- Framework: <e.g. Next.js 14 App Router>
- Key libraries: <e.g. Prisma, tRPC, Tailwind>

## How to run
- Install: `<cmd>`
- Dev server: `<cmd>`
- Tests: `<cmd>`
- Lint/format: `<cmd>`

## Conventions
- <e.g. Use functional components; no class components.>
- <e.g. Co-locate tests as *.test.ts next to source.>
- <e.g. Conventional Commits for messages.>

## Guardrails
- Run the tests before saying a task is done.
- Don't edit files under `/generated` or `/vendor`.
- Never commit secrets or .env files.

## Good to know
- <Gotchas, non-obvious decisions, links to deeper docs.>

Node / TypeScript Web 应用​

# Project: <name> (Next.js + TypeScript)

## How to run
- Dev: `npm run dev`
- Build: `npm run build`
- Test: `npm test`
- Lint: `npm run lint` (must pass before commit)

## Conventions
- TypeScript strict; no `any` without a comment justifying it.
- Components in `src/components`, one folder per component.
- Data fetching via tRPC; never call the DB from a client component.
- Styling: Tailwind utility classes; no inline styles.

## Guardrails
- After any change, run `npm run lint && npm test`.
- Keep files under ~300 lines; split when larger.
- Do not modify `prisma/migrations` by hand.

Python 服务​

# Project: <name> (FastAPI)

## How to run
- Install: `uv sync` (or `pip install -e .`)
- Dev: `uvicorn app.main:app --reload`
- Test: `pytest`
- Lint/format: `ruff check . && ruff format .`

## Conventions
- Type hints everywhere; prefer `pathlib` over `os.path`.
- Pydantic models for all request/response bodies.
- f-strings, not %-formatting.

## Guardrails
- Run `pytest` and `ruff check` before completing a task.
- Fail fast with descriptive errors; no silent excepts.

适用于以上全部模板的小贴士​

  • 分层使用。 用一个仓库根目录的 CLAUDE.md 管理整个项目；在子文件夹里放嵌套的 CLAUDE.md 文件来制定特定区域的规则。
  • 使用 @imports 来引入现有文档，而不是重复编写它们（参见 CLAUDE.md 参考）。
  • 每月复查一次。 过时的指令比没有指令更糟。

相关内容​