aaihubhub
← 文章库
Claude Code 小白进阶课：从第一次对话到可靠协作 · 第 6 课 / 共 20 课 ↗ AI 教程

06｜CLAUDE.md 实战：写一份真正有用的项目说明

从项目模板出发编写架构、命令、规范和边界。

kimi
LESSON BRIEFING06 / 20

从项目模板出发编写架构、命令、规范和边界。

CLAUDE.md 不是百科全书，而是新同事上岗第一天贴在显示器旁的便签：怎么启动、怎么验证、哪些区域不要碰、团队真正坚持什么。过长的说明会让关键规则失焦。

向 Claude Code 询问项目记忆

Claude Code 保存项目记忆后的界面

本课交付物

为练习仓库编写不超过 60 行的 CLAUDE.md，包含架构地图、标准命令、代码约定、危险区和完成定义；开启新会话验证它是否被正确遵守。

开发规范

代码风格

命名约定

Git 工作流

测试要求

API 规范

数据库

部署

常用命令

团队联系人

已知问题与解决办法

相关项目

示例 2：目录级记忆

# API 模块规范
## API 专属规范
### 请求校验
### 身份验证
### 响应格式
### 分页
### 限流
### 缓存

示例 3：个人记忆

# 我的开发偏好
## 关于我
## 代码偏好
### 错误处理
### 注释
### 测试
### 架构
## 调试偏好
## 沟通方式
## 项目组织
## 工具链

示例 4：会话中更新记忆

两种常见方式：

  1. 直接提要求，让 Claude 把规则写进 memory
  2. 使用 # new rule into memory 这种模式追加规则

最佳实践

应该做的

  • 用项目记忆保存团队标准
  • 用目录记忆保存局部差异
  • 先写简洁规则，再逐步补充
  • 把可重复内容写进 CLAUDE.md

不应该做的

  • 不要把 README 整份复制进 CLAUDE.md
  • 不要把明显属于代码的实现细节硬塞进 memory
  • 不要让 memory 变成垃圾桶

记忆管理建议

  • 优先引用已有文档，而不是重复粘贴
  • 只保留真正影响 Claude 行为的信息
  • 定期整理过期或冲突的规则

安装说明

设置项目记忆

方法 1：使用 /init（推荐）

/init

方法 2：手动创建

cp project-CLAUDE.md CLAUDE.md

方法 3：快速更新

# Use semantic versioning for all releases
# Always run tests before committing
# Prefer composition over inheritance

设置个人记忆

cp personal-CLAUDE.md ~/.claude/CLAUDE.md

设置目录记忆

cp directory-api-CLAUDE.md src/api/CLAUDE.md

验证安装

  • 重新打开 Claude Code 会话
  • 检查 CLAUDE.md 是否被自动加载
  • 用一条明显会受 memory 影响的提示词测试

官方文档

如果你想看更详细的行为定义、兼容性和最新限制，建议参考 Claude Code 官方 memory 文档。

相关概念

  • Slash Commands 中文参考
  • Skills 中文指南
  • Subagents 中文参考
  • Advanced Features 中文指南

团队联系人

  • 技术负责人：Sarah Chen（@sarah.chen）
  • 产品经理：Mike Johnson（@mike.j）
  • 运维：Alex Kim（@alex.k）

已知问题与解决方案

  • PostgreSQL 连接池在高峰期限制为 20
  • 解决方法：实现查询排队
  • Safari 14 对 async generator 的兼容性有问题
  • 解决方法：使用 Babel 转译器

关联项目

  • 分析仪表盘：/projects/analytics
  • 移动端 App：/projects/mobile
  • 管理后台：/projects/admin

本站实战工作台

把它当成新同事桌边的说明卡

CLAUDE.md 的价值不是把整个项目抄进去，而是让每次新会话都从同一组关键事实开始。最有用的内容通常只有五类：项目地图、标准命令、代码约定、危险区域、完成定义。它应该帮助 Agent 更快找到证据，而不是要求 Agent 相信一篇永远不会过期的百科。

先收集事实，再写规则

从 README、package.json、CI 配置和现有测试里核对启动与验证命令。不要凭印象写 npm test；项目可能要求特定 Node 版本或额外环境变量。把每条规则问成一个问题：“如果删掉它，Agent 是否更可能犯真实错误？”答案是否定的，就不该占据长期上下文。

# Project map
- frontend/: Nuxt public site and admin
- service/: Nest API and Prisma

# Verify
- Frontend tests: npm test
- Production build: use the pinned Node runtime

# Boundaries
- Preserve unrelated worktree changes
- Never print or commit secrets

# Done
- Test, build, browser evidence, and rollback note

指令要具体到行为

“保持高质量”无法执行；“新增可见文案必须同时增加 zh/en 相同 key”可以检查。“小心数据库”仍然模糊；“禁止 reset，迁移前备份，发布后检查 migration status”才是控制规则。

避免把临时任务写进永久记忆。今天要改首页轮播，不代表今后每个任务都需要读轮播实现。临时目标留在任务卡，稳定约定才进入 CLAUDE.md。

60 行实验

为练习仓库写一份不超过 60 行的 CLAUDE.md。关闭当前会话，开启新会话，只问三件事：怎样验证、哪些目录危险、完成后交付什么证据。若回答需要翻阅大量无关文件，说明说明卡缺少入口；若它机械复述长段文字，说明说明卡太重。

再故意写一条与 package.json 冲突的测试命令，观察 Agent 会盲从还是用仓库事实指出矛盾。长期指令拥有高影响力，因此也必须可被验证和修正。

维护而不是堆积

当架构、命令或发布方式变化时，同一个提交里更新说明。每季度或大版本后审计一次：删除已失效路径，合并重复规则，把事故中真正有复发价值的教训留下。Git 历史已经保存旧版本，不需要在文件里保留“过去曾经……”的考古段落。

验收

一位不了解项目的人只读这份说明，能找到入口、运行正确检查、避开危险区；文件中的每个命令都在当前仓库验证过；没有密钥、个人路径和一次性任务。做到这些，它才是项目记忆，而不是项目负担。