Perplexity-CLAUDE.md

下面用“可跨项目复用”和“只属于某个项目”这两个标准，帮你把内容明确拆成两类：写进全局 ~/.claude/CLAUDE.md vs 写到项目级 CLAUDE.md。

一、适合写进全局 `~/.claude/CLAUDE.md` 的内容

原则：几乎所有项目都适用、长期稳定、是你的个人/团队习惯。[1][2]

1. 个人工作流与默认习惯

默认工作方式：
- “先理解再动手”、“先规划再实现”、“先验证再收尾”。
- 遇到错误优先用检查输出（lint/test/build）驱动修复。
会话卫生：
- 会话混乱时建议清空上下文、重启。
- 不在这个文件里写临时任务。
多项目协作习惯：
- 项目差异放到项目级 CLAUDE.md。
- 不在这个文件里放项目特定规则。

2. 通用编码规范（不绑定具体框架）

风格总则：
- 遵循项目现有风格和模式。
- 优先小 diff、最小改动。
- 避免过度抽象和过度设计。
- 命名清晰、一致，实现简单。
错误处理原则（通用）：
- 优先明确、可理解的错误信息。
- 避免吞掉错误，必要时打印上下文。
- 不写“万能 try-catch”之类模糊策略（除非你明确要这样）。

3. 验证与测试原则（通用）

验证策略：
- 有 lint/test/build 时必须跑。
- 小改动优先针对性测试，而不是全量跑。
- bug 修复时，加/改一个能复现的测试。
- UI 改动尽量手动验证。
失败处理：
- build/lint/test 失败先修复再继续。

4. Git / PR / 分支习惯（通用）

Commit：
- 描述清晰、简短。
- 每个 commit 聚焦一个任务。
历史：
- 不重写历史，除非明确要求。
分支/PR：
- 尊重仓库已有的分支和 PR 约定（不写具体规则，只写原则）。

5. 你的个人偏好（跨项目）

适合写：

默认平台：macOS + CLI 优先。
工具偏好：简单、可脚本化的方案 > 复杂 GUI。
Obsidian 相关：
- 遵守 markdown 约定。
- 不破坏笔记链接。
AI 工具/API 配置：
- 优先小且可测试的改动。
- 要求清晰的错误信息。
终端/移动端集成习惯（如 Termux、mobile + CLI）等。

这些是你的个人风格，不依赖具体项目，适合全局。

6. 语言与文档风格（通用）

文档 / 注释风格总则：
- 注释解释“为什么”，而不是重复“做什么”。
- README / 文档要简单、可执行（有步骤、有示例）。
语言偏好（如果你希望 Claude 默认用中文/英文）：
- 例如：“默认用中文回答，技术文档用英文，除非项目明确要求。”

二、适合写到项目级 `CLAUDE.md` 的内容

原则：只在这个项目里成立、会随项目变化、绑定具体技术栈或团队规范。[2][1]

1. 项目目标与背景

项目是什么：
- 业务目标、核心功能、用户群体。
关键设计决策：
- 为什么选这个架构、这个框架、这个数据库。
当前阶段：
- 正在做什么重点（迁移、重构、新功能等）。
已知历史问题：
- 曾经踩过的坑、不能随便改的地方。

这些内容只对这个项目有意义，绝对不能放全局。

2. 技术栈与具体框架约束

确切技术栈：
- 例如：React + TypeScript + Vite + Tailwind。
- 后端：Node.js + Express + PostgreSQL。
框架特定规则：
- 使用 App Router 而不是 Pages Router。
- 特定组件库的用法、禁用某些 API。
语言/版本约束：
- 例如：必须用 ES2022，不能用某些新版本语法。
依赖管理：
- 使用 pnpm/yarn/npm 的约定。
- 是否允许某些依赖，是否禁止某些包。

这些是项目特有的，放全局会让其他项目被误导。

3. 项目特定的代码风格与约定

文件结构约定：
- 例如：src/pages、src/components、src/lib 的布局。
命名约定（项目级）：
- 例如：组件用 PascalCase，工具函数用 camelCase，测试文件后缀.test.ts。
导入约定：
- 绝对导入 vs 相对导入。
- 使用 @/ 别名还是不用。
样式约定：
- CSS Modules / Tailwind / styled-components 的具体使用规则。
API 约定：
- 路由前缀、响应格式、错误码格式。

这些通常只在项目中生效，放全局会强制到所有项目。

4. 项目特定的命令与验证流程

具体命令：
- npm run build、pnpm test、yarn lint 等。
- 特定脚本：pnpm migrate、npm run seed。
测试策略（项目级）：
- 用 Jest/Vitest/Playwright，覆盖哪些目录。
- CI 配置要求。
构建/部署：
- 使用 Vite、Rollup、Webpack 的具体配置约定。
- Docker 构建步骤、部署流程。

这些命令和流程只在项目内有效，放全局会让 Claude 在其他项目里跑错命令。

5. 项目特定的 Git / 分支 / PR 规范

分支命名：
- 例如：feature/xxx、hotfix/xxx、release/x.y。
PR 模板：
- PR 必须包含哪些内容（检查清单、截图、影响范围）。
Rebase / merge 策略：
- 是否强制 rebase，是否允许 merge commit。
提交规范：
- 是否用 feat:、fix:、Breaking: 等前缀。

这些是团队/项目约定，不适合全局。

6. 项目特定的安全/隐私/合规要求

安全策略：
- 哪些数据不能日志化。
- 必须加密的字段。
隐私/合规：
- GDPR、用户数据保留策略。
内部规范：
- 某些平台/内部系统的访问限制。

这些也是项目/组织特定的。

7. 项目临时任务 / 短期迁移 / 一次性说明

临时迁移步骤：
- 例如：从 Pages Router 迁移到 App Router 的阶段性说明。
短期任务：
- 当前正在做的重点功能、待办列表。
已知 bug 清单：
- 项目当前未修复的 bug。

这些会随时间变化，绝对不要放全局。

三、快速判断规则（一句话总结）

对每一条规则，问自己两个问题：

如果删掉这条，会不会让 Claude 在“几乎所有项目”里更容易犯错？
- 是 → 适合全局。
- 否 → 再看下一条。
这条规则是否只在当前项目成立，或者会随项目变化？
- 是 → 项目级。
- 否 → 可能适合全局。

简单版：

全局：
- 你的个人习惯、通用工作流、通用编码/测试/Git 原则、跨项目偏好。
项目级：
- 项目目标、技术栈、框架规则、具体命令、团队规范、临时任务。

来源 [1] Writing a good CLAUDE.md | HumanLayer Blog https://www.humanlayer.dev/blog/writing-a-good-claude-md [2] Claude Code: Best practices for agentic coding - Anthropicanthropic.com › engineering › claude-code-best-practices https://www.anthropic.com/engineering/claude-code-best-practices

一、适合写进全局 ~/.claude/CLAUDE.md 的内容