用 project-CLAUDE.md 为 Claude Code 建立团队级项目记忆：完整配置指南与模板拆解

用 project-CLAUDE.md 为 Claude Code 建立团队级项目记忆完整配置指南与模板拆解【免费下载链接】claude-howtoA visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-howto项目级CLAUDE.md即本仓库zh/02-memory/project-CLAUDE.md模板所代表的记忆文件是 Claude Code 在跨会话间保留上下文的核心机制把团队规范、架构约定、编码标准、Git 工作流写进一个文件Claude 每次会话启动都会自动加载。本文以该模板为骨架逐节拆解其字段含义与落地姿势并结合本仓库真实的CLAUDE.md、目录级与个人级记忆文件讲清项目记忆该写什么、怎么写、放在哪、如何验证让你 15 分钟内在自己的项目里把 Claude 的默认行为调教成团队标准。一、为什么需要项目级记忆从每次重说到自动遵守Claude Code 的上下文窗口只在单次会话内有效一旦关闭终端你反复强调的本项目用 2 空格缩进、提交信息必须遵循 conventional commits就全部丢失。Memory 体系把这类规则固化到文件系统中跨会话持久CLAUDE.md文件在每次会话启动时自动加载规则始终在场团队共享项目级记忆跟随 git 提交5 人团队只要各自拉取仓库就获得同一套规范分层生效从组织级受管策略、用户级个人偏好到项目级团队规范、子目录级模块约束逐层拼接进上下文实现全局默认 局部覆盖。本仓库02-memory/目录提供了三种可复制的模板project-CLAUDE.md团队项目规范复制为./CLAUDE.md、personal-CLAUDE.md个人偏好复制为~/.claude/CLAUDE.md、directory-api-CLAUDE.md目录级规范复制为src/api/CLAUDE.md。本文聚焦第一种也就是最常见的落地场景。二、三分钟上手把项目记忆装进你的仓库方法一/init一键初始化推荐在项目根目录启动 Claude Code输入/initClaude 会扫描当前项目生成一个结构完整的CLAUDE.md通常落在./CLAUDE.md或./.claude/CLAUDE.md骨架与本仓库模板一致# 项目配置 ## 项目概览 ## 开发规范随后按需增删章节即可。若希望init走多阶段交互式引导分步询问项目信息可以这样启动CLAUDE_CODE_NEW_INIT1 claude /init方法二直接复制模板最快把本仓库的模板拷到自己的项目根目录然后逐项改写成你的实际情况cp zh/02-memory/project-CLAUDE.md /path/to/your-project/CLAUDE.md这也是仓库根README.md的15 分钟快速上手推荐路径见 README.md 的 Get Started 一节cp 02-memory/project-CLAUDE.md ./CLAUDE.md。方法三会话中追加规则想让 Claude 记住一条新规则直接口语化提出即可#前缀快捷写法在新版本中已弃用请记住这个项目所有新组件都使用 React Hooks 函数组件Claude 会反问保存到哪个作用域项目记忆./CLAUDE.md/ 个人记忆~/.claude/CLAUDE.md确认后写入对应文件并自动重载。验证是否生效重新打开一个 Claude Code 会话观察会话启动时CLAUDE.md是否被自动加载用一条明显受记忆影响的提示词测试例如检查这个文件的命名是否符合规范确认 Claude 遵循了你写入的规则。三、逐节拆解 project-CLAUDE.md每段写什么、为什么原模板的组织顺序本身就是一份项目记忆最佳目录结构。下面逐节说明每个字段的用途与写法要点。1. 项目概览给 Claude 的第一印象## 项目概览 - **名称**电商平台 - **技术栈**Node.js、PostgreSQL、React 18、Docker - **团队规模**5 名开发者 - **截止时间**2025 年第 4 季度这段决定了 Claude 对项目语境的基本判断用什么语言写代码、面向什么环境部署、节奏多紧。技术栈尤其重要——Claude 会据此选择合理的依赖、构建与调试策略。2. 架构用导入替代复制粘贴## 架构 docs/architecture.md docs/api-standards.md docs/database-schema.md这是CLAUDE.md最值得掌握的语法path/to/file会把外部文档内容在加载时直接并入上下文。要点支持相对路径与绝对路径如~/.claude/my-instructions.md递归导入最大深度为 4 层首次导入外部文件会触发安全确认对话框代码块或行内代码中的...不会被当作导入指令因此可以在文档里安全地讲解该语法。核心收益是单点维护架构文档更新后记忆自动跟随最新版无需手工同步——这正是模板用而非复制内容的原因。3. 代码风格机器可执行的硬约束### 代码风格 - 使用 Prettier 格式化 - 使用带 airbnb 配置的 ESLint - 最大行长度100 字符 - 使用 2 空格缩进这里的原则是具体、可验证与其写保持代码整洁不如写最大行长度 100 字符、2 空格缩进。Claude 写出的代码会逐条对齐这些硬性约束等效于把 lint 规则前置到生成阶段。4. 命名规范一张表统一全队认知### 命名规范 - **文件**kebab-caseuser-controller.js - **类**PascalCaseUserService - **函数 / 变量**camelCasegetUserById - **常量**UPPER_SNAKE_CASEAPI_BASE_URL - **数据库表**snake_caseuser_accounts命名规范是 Claude 生成新文件、新符号时最常踩坑的地方用表格写明各作用域的命名范式后产出的代码风格会自动趋同。5. Git 工作流规范提交与合并门槛### Git 工作流 - 分支命名feature/description 或 fix/description - 提交信息遵循 conventional commits - 合并前必须有 PR - 所有 CI/CD 检查都必须通过 - 至少需要 1 个 approval写清楚分支前缀、提交信息格式、PR 与 CI 门槛Claude 生成的提交信息type(scope): subject与分支名会自动符合仓库约定。本仓库自身的 CLAUDE.md 就是这样实践的——其 Hard rules 一节规定提交格式type(scope): subjectscope 与模块目录对应如docs(memory):。6. 测试要求把覆盖率底线写进上下文### 测试要求 - 最低 80% 代码覆盖率 - 所有关键路径都必须有测试 - 单元测试使用 Jest - E2E 测试使用 Cypress - 测试文件名*.test.ts 或 *.spec.ts明确框架选型与覆盖率底线后Claude 在补测试类任务中会自动对齐测试栈、命名与覆盖目标。7. API 规范接口风格的统一契约### API 规范 - 只允许 RESTful 端点 - 请求 / 响应都使用 JSON - 正确使用 HTTP 状态码 - API 版本路径/api/v1/ - 所有端点都要带示例文档如果项目对 API 有更细的要求校验、认证、分页、限流、缓存不要堆进根文件而是用目录级记忆承载——见本仓库 zh/02-memory/directory-api-CLAUDE.md它定义了 Zod 请求校验、JWT 认证、统一响应结构、cursor 分页、限流配额、Redis 缓存等完整契约专门作用于src/api/目录。8. 数据库与部署把运维红线写清楚### 数据库 - schema 变更使用 migrations - 绝不硬编码凭据 - 使用连接池 - 开发环境启用查询日志 - 需要定期备份 ### 部署 - 基于 Docker 的部署 - 使用 Kubernetes 编排 - 蓝绿部署策略 - 失败时自动回滚 - 部署前先执行数据库迁移这两节属于防止事故型规则迁移先行、凭据不入库、部署顺序等都是 Claude 参与运维类任务时最容易被纠正的点。9. 常用命令表把重复输入交给记忆命令作用npm run dev启动开发服务器npm test运行测试套件npm run lint检查代码风格npm run build构建生产版本npm run migrate执行数据库迁移项目记忆里放一张高频命令速查表Claude 就不需要每次去翻package.json或追问你。本仓库的 CLAUDE.md 同样维护了 Critical commands 一节pre-commit run --all-files、pytest scripts/tests/ -v、uv run scripts/build_epub.py等可作为真实范例参考。10. 团队联系人跨会话的人肉路由## 团队联系人 - 技术负责人Sarah Chensarah.chen - 产品经理Mike Johnsonmike.j - 运维Alex Kimalex.k让 Claude 知道哪类问题该找谁在处理需要人工介入的事项时能给出准确指向。11. 已知问题与解决方案沉淀踩坑经验## 已知问题与解决方案 - PostgreSQL 连接池在高峰期限制为 20 - 解决方法实现查询排队 - Safari 14 对 async generator 的兼容性有问题 - 解决方法使用 Babel 转译器这是团队最容易忽视却最值钱的一节把已知坑 解法固化进记忆Claude 再遇到同类问题时会直接给出已验证的答案而不是重新踩一遍。12. 关联项目上下文里的项目地图## 关联项目 - 分析仪表盘/projects/analytics - 移动端 App/projects/mobile - 管理后台/projects/admin在多仓库或微服务场景下标明关联项目路径Claude 就能理解当前仓库在整个系统中的位置。四、记忆的分层体系项目、目录、个人如何协作记忆不是单一文件而是一个分层拼接的体系。本仓库提供了另外两个模板做对照记忆层级文件位置典型内容本仓库模板受管策略组织级macOS/Linux/Windows 系统目录合规、安全、统一流程—用户记忆~/.claude/CLAUDE.md个人偏好、工具链、沟通风格zh/02-memory/personal-CLAUDE.md项目记忆./CLAUDE.md架构、编码标准、Git 工作流zh/02-memory/project-CLAUDE.md目录记忆./src/api/CLAUDE.md模块约束、局部规范zh/02-memory/directory-api-CLAUDE.md关键机制详见 zh/02-memory/README.md 的 Memory Hierarchy 一节拼接而非覆盖所有CLAUDE.md文件按受管策略 → 用户规则 → 用户记忆 → 项目规则 → 项目记忆 → 本地项目记忆的顺序全部拼进上下文而不是高层替换低层。目录级文件是对根文件的补充根规则依然生效就近加载从工作目录向上逐层发现CLAUDE.md工作目录之下的子目录文件在 Claude 实际读取该目录内容时按需加载本地私货./CLAUDE.local.md存放仅个人可见的项目内偏好应加入.gitignore不进版本库排除机制在~/.claude/settings.json或.claude/settings.json中用claudeMdExcludes排除巨型 monorepo 中无关子项目的记忆文件{ claudeMdExcludes: [ packages/legacy-app/CLAUDE.md, vendors/**/CLAUDE.md ] }另外注意Claude 还会自动维护一份auto memory~/.claude/projects/project/memory/入口MEMORY.md会话启动时加载前 200 行/25KB用于记录它自己观察到的模式与偏好与手写的CLAUDE.md是两套互补系统。五、真实范例本仓库自己的 CLAUDE.md 是怎么写的仓库根目录的 CLAUDE.md 就是项目记忆的活教材它展示了项目级记忆还能承载哪些元信息Critical commands把质量门禁pre-commit run --all-files、测试pytest scripts/tests/ -v、构建uv run scripts/build_epub.py等关键命令写进记忆Architecture map用目录级别的说明01-10-模块按学习顺序编号、scripts/仅用于校验与构建让 Claude 理解仓库的角色边界——正如模板中架构一节的作用Hard rules不可违背的硬约束如未经用户明确要求不得提交或推送、代码围栏必须声明语言与模板的Git 工作流/数据库/部署红线一脉相承Token Efficiency要求 Claude 不重读刚写过的文件、合并编辑、避免多余确认——这类如何与 Agent 协作的元规则同样适合放进项目记忆。从这个例子可以看到模板给出的 12 个章节是可裁剪的起点你的项目记忆完全可以按需增加质量门禁、硬性红线、协作偏好等自定义章节。六、最佳实践写什么、不写什么应该做项目记忆存团队标准架构、编码规范、Git 工作流、测试要求随 git 共享目录记忆存局部差异模块专属规则如 API 目录的校验/认证/分页契约放子目录CLAUDE.md先简洁后扩充先写几条最关键规则跑起来再逐步沉淀用导入已有文档优先引用而非复制保证单点维护控制篇幅官方建议每个CLAUDE.md控制在200 行以内——它每个会话都会完整加载行数越多对无关任务的注意力稀释越严重。内容膨胀时把多步骤流程迁到 skill、把路径专属规则迁到.claude/rules/*.md用paths:frontmatter 按 glob 生效纳入版本控制提交CLAUDE.md让全队共享并留下变更历史。不应该做不要把 README 整份复制进CLAUDE.md——改用README.md导入不要把代码实现细节硬塞进 memory——那是源码该管的事不要让 memory 变成垃圾桶——只保留真正会改变 Claude 行为的信息不要写验证提醒类规则如完成后记得跑测试在 Claude Opus 5 / Fable 5 等新模型上这类提示会引发过度验证白白消耗轮次与 token改成陈述目标让 Claude 自行判断绝不放密钥与敏感信息凭据、token、PII 一律不进CLAUDE.md。维护节奏新增单条规则直接用/memory打开记忆编辑器或口语化让 Claude 写入批量调整用/memory打开./CLAUDE.md统一整理保存后 Claude 自动重载定期审计随着项目演进清理过期、冲突的规则当文件明显超出 200 行且adherence下降时考虑把内容外移到 skill 或rules/目录。七、小结project-CLAUDE.md本质上是一份可版本化、可共享、自动加载的团队协作契约。把项目概览、架构导入、代码风格、命名规范、Git 工作流、测试要求、API 规范、数据库与部署红线、常用命令、联系人、已知问题与关联项目写进./CLAUDE.mdClaude Code 便能在每个会话中自动遵循这套标准。配合目录级记忆directory-api-CLAUDE.md、个人记忆personal-CLAUDE.md与文档导入机制你可以在不增加上下文负担的前提下把规则精确作用到每一个层级——这也是本仓库02-memory/模块想传递的核心能力。【免费下载链接】claude-howtoA visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-howto创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考