Claude Code使用教程 第4篇:Claude.md作用之一,项目级说明书

今天分享的主题是CLAUDE.md ,本篇讲介绍它作为项目说明书的场景。

什么是 CLAUDE.md

CLAUDE.md 是项目根目录的一个文件,告诉 Claude 这个项目的基本信息。

Claude 每次启动会自动读取这个文件,所以你不用每次都解释项目背景。

创建 CLAUDE.md

在项目根目录创建:

bash 复制代码
cat > CLAUDE.md << 'EOF'
# 计算器项目

## 技术栈
TypeScript + Node.js

## 项目结构
src/
  calculator.ts  --- 计算器核心逻辑
  utils.ts       --- 工具函数
tests/
  calculator.test.ts --- 测试文件

## 编码规范
• 函数名用 camelCase
• 必须写 JSDoc 注释
• 每个函数要有对应的测试

## 注意事项
• 除法要处理除数为 0 的情况
• 所有数字用 number 类型
EOF

验证 CLAUDE.md 生效

启动 Claude Code:

bash 复制代码
claude

输入:

复制代码
这个项目的编码规范是什么?

Claude 自动读取了 CLAUDE.md 的内容。

Claude中推荐写的内容

CLAUDE.md 建议包含:

  1. 项目简介 --- 这是什么项目,解决什么问题
  2. 技术栈 --- 语言、框架、主要依赖
  3. 项目结构 --- 主要目录和文件的说明
  4. 编码规范 --- 命名、注释、代码风格
  5. 注意事项 --- 容易踩坑的地方

实际案例

来自 modelcontextprotocol/servers 项目(MCP 官方参考服务器实现):

markdown 复制代码
# CLAUDE.md

This file provides guidance to Claude Code when working with code in this repository.

## Project Overview

Official MCP reference server implementations. This is an npm workspaces monorepo
containing 7 servers (4 TypeScript, 3 Python) under src/.

## Monorepo Structure

src/
  everything/          TS  @modelcontextprotocol/server-everything
  filesystem/          TS  @modelcontextprotocol/server-filesystem
  memory/              TS  @modelcontextprotocol/server-memory
  ...

## Build & Test Commands

### TypeScript servers
cd src/<server> && npm ci && npm run build && npm test

### Python servers
cd src/<server> && uv sync --frozen --all-extras --dev
uv run pytest

## Code Style

### TypeScript
- ES modules with .js extension in import paths
- Strict TypeScript typing for all functions
- Zod schemas for tool input validation
- camelCase for variables/functions, PascalCase for types/classes

### Python
- Type hints enforced via pyright
- Async/await patterns

这个案例展示了 CLAUDE.md 的典型结构:项目概述、目录结构、构建命令、代码风格。信息简洁但关键。

优先级

CLAUDE.md 有两个级别:

级别 位置 优先级
项目级 项目根目录 高
全局级 ~/.claude/ 低

当两个文件同时存在时,Claude 会合并读取,项目级的配置会覆盖全局的同名配置。

建议:项目相关写项目级 CLAUDE.md,通用偏好写全局 CLAUDE.md。

最佳实践

  • 控制在 500 字以内,只写关键信息
  • 提交到 Git,团队成员共享
  • 项目变动时及时更新

避坑提示

别写太长。

太长的 CLAUDE.md:

  • Claude 每次启动要花时间读
  • 可能记不住所有内容

建议:只写关键信息,控制在 500 字以内,使得Claude能够抓住重点,也可以省去每次加载的token量。

相关推荐
黎羽_16 小时前
Claude 免费号 7 天养号毕业全记录:54 轮对话、IP 预检与月度维护
claude·免费账号·muse·ai 养号
ZzT17 小时前
AI-SDLC 实践 06|开发阶段的知识库:Agent 写代码前该读哪些规则和业务知识
ai编程·claude
小七-七牛开发者1 天前
Anthropic:Agent 不必一直运行,也能持续工作
agent·claude·deepseek·anthropic·alwaysonagent
孟健2 天前
用T3 Code手机远程控制Claude Code完成周报总结实测
开源·ai编程·claude
武子康3 天前
H3-World 动作控制怎么测:从左右对照到片内切换
人工智能·agent·claude
小七-七牛开发者3 天前
PACE:代码通过率从 42% 到 97%, 让长程 Agent 在有限 KV Cache 下用好历史 Token
大模型·claude·token·工作流·长程agent
ZzT3 天前
沙箱不再自动放行、项目配置默认禁用:Claude Code 与 Codex 升级适配指南
ai编程·claude
ZhengEnCi3 天前
AI 规则越多越费 Token:无关规则让每次回答多耗 46% 的规则体检提示词
aigc·ai编程·claude
ServBay3 天前
连AI自己也不愿意维护自己的屎山代码
后端·ai编程·claude
jerrywus4 天前
用 AMD Radeon Cloud 免费跑 ComfyUI:从开机到打开界面
前端·agent·claude