Appearance
整理时间：2026-04-29 | 来源：官方文档、社区实践、安全审计报告
一、CLAUDE.md配置原则
核心原则：保持简短
- 控制在60行以内，硬上限300行
- LLM能可靠遵循约150-200条指令，Claude Code系统提示已占用约50条
- 只放Claude可能忽略的信息：构建命令、测试命令、分支命名规范、项目特定架构决策
- 能从代码推断的内容不要写进去
- 规则太多？拆分到
.claude/rules/目录下按需加载 - 关键规则用标签包裹防止被忽略
好的CLAUDE.md结构示例
markdown
## 工作流
- 每次代码变更后运行 `npm test`
- 每个任务创建新分支，绝不直接提交到main
- 使用Conventional Commits（feat:、fix:、refactor:、docs:）
- 完成后通过 `gh pr create` 创建PR
## 技术栈
- Node.js 18+, Express 4.x, PostgreSQL 16
- 测试：Jest + React Testing Library
- 认证：JWT + bcrypt二、工作流最佳实践
1. 复杂任务用Plan Mode
按Shift+Tab两次进入计划模式，Claude只研究和规划，不写代码。确认计划后再切换回正常模式执行。
官方推荐流程： 探索 → 规划 → 实现 → 提交
2. 让Claude先采访你
给出简单需求描述，让Claude用AskUserQuestion工具采访你，它能发现你忽略的边缘情况。采访后开新会话执行（采访对话会污染上下文）。
3. 分阶段工作流
理解代码库 → 修改；先规划 → 再实现；生成 → 验证。不要把所有步骤压缩到一个大提示词里。
4. 小任务别用复杂工作流
3-5分钟能完成的事，直接用原生Claude Code。复杂工作流（Superpowers、Spec Kit等）适用于多文件、多步骤的大任务。
三、调试与纠错
1. 粘贴bug，说"fix"
把错误信息粘贴给Claude，说一个字："fix"。不要指导怎么修，不要猜测原因，不要指定解决方案。Claude的调试能力比想象中强，管得越多越容易带偏。
2. 两次失败 = /clear
同一个问题修正超过两次，/clear重新开始。上下文污染会降低性能。官方建议：修正超过两次就重启。
3. 走偏了？Esc Esc回滚
按两次Esc（或/rewind）直接回滚到上一个检查点。在同一上下文中纠正偏差往往更糟。
4. 要求重写平庸方案
当Claude给出能工作但不优雅的解决方案时，不要修补。说："知道你现在知道的一切，抛弃这个，实现优雅的解决方案"。
四、上下文管理
1. 50%时手动压缩
上下文使用超过60-70%时，性能明显下降。在50%时手动执行/compact，不要等自动压缩。
2. /compact可指定压缩策略
bash
/compact focusing on API changes # 聚焦API变更压缩
/compact keep test-related history # 保留测试相关历史
/compact keep error resolution # 保留错误解决历史3. Checkpoints（检查点）
- 每次Claude操作自动创建
- 可独立回滚对话或代码
- 跨会话持久化
- 不是git的替代品
五、Subagents（子智能体）
1. 在提示词中加"use subagents"
Claude会自动拆分任务给多个子智能体并行处理。适合代码审查、大规模重构。
2. 专用子智能体 > 通用mega-agent
创建功能特定的子智能体（如"前端组件智能体"），而不是通用的（如"QA智能体"）。
3. 子智能体有独立上下文窗口
研究、验证、审查隔离在独立上下文中，防止污染主上下文。
六、Skills（技能）管理
1. 技能应该是文件夹结构
skills/
├── api-design/
│ ├── SKILL.md # 主文件：核心规则和索引
│ ├── references/ # 语料库、参考资料
│ ├── scripts/ # 辅助脚本
│ └── examples/ # 示例代码主文件只包含核心规则和索引，语料库、检查表放在references/。
2. 添加Gotchas（坑点记录）
这是长期最有价值的技术：每次Claude犯错时记录失败模式，长期积累成为信噪比最高的内容。
markdown
## Gotchas（坑点记录）
### 2026-04-15: API分页参数遗漏
- **问题**：生成API时忘记添加分页参数
- **表现**：返回所有数据导致性能问题
- **修复**：在SKILL.md中添加分页规则
- **预防**：检查清单中增加"是否包含分页"Gotchas维护原则：
- 每次犯错必记录：不要等，立即记录
- 包含四个要素：问题描述、表现形式、修复方法、预防措施
- 定期回顾：每周回顾一次，识别重复出现的模式
- 转化为规则：如果某个坑点出现3次以上，转化为正式规则
七、Superpowers使用详解
什么是Superpowers
Superpowers是由Jesse Vincent和Prime Radiant团队开发的Claude Code插件（14万+GitHub stars），解决工程纪律问题。
核心功能：
- 强制结构化工作流：头脑风暴 → 分支隔离 → 详细计划 → 执行
- TDD（测试驱动开发）
- 代码审查
- 系统调试
- 验证完成
安装
bash
/plugin install superpowers@claude-plugins-official技能激活方式
| 技能 | 何时激活 | 触发方式 |
|---|---|---|
| brainstorming | 创建功能或组件前 | 单独使用时自动 |
| writing-plans | 需求需要多步分解时 | 单独使用时自动 |
| test-driven-development | 实现功能或修复bug前 | 需在CLAUDE.md中显式配置 |
| systematic-debugging | 遇到bug、测试失败时 | 需在CLAUDE.md中显式配置 |
| code-reviewer | 完成主要实现步骤后 | 需在CLAUDE.md中显式配置 |
| verification-before-completion | 声称工作完成前 | 需在CLAUDE.md中显式配置 |
八、OpenSpec使用详解
什么是OpenSpec
OpenSpec是Fission AI开发的开源框架，将一句话需求扩展为四个结构化文档：
proposal.md：为什么、范围、不在范围内什么specs/：使用GIVEN/WHEN/THEN场景的行为规范design.md：技术决策及推理tasks.md：实现清单，每个任务2-5分钟可完成
安装
bash
npm install -g @fission-ai/openspec@latest
cd your-project
openspec init # 选择Claude Code工作流程
bash
# 会话1：需求 → 规范
> /opsx:propose 用户认证API，Express + MongoDB + JWT
# 会话2：规范 → 实现
> /opsx:apply
# 会话3：独立验证
> /opsx:archive # 归档当前迭代九、权限与安全
Hooks vs CLAUDE.md
| 需求 | 推荐 | 原因 |
|---|---|---|
| 文件保存后自动lint | Hook | 每次必须执行 |
| 阻止写入敏感文件 | Hook | 安全不能妥协 |
| 代码规范遵循 | CLAUDE.md | 需要情境判断 |
deny比Hooks更安全
json
{
"permissions": {
"deny": [
"Read(./.env)",
"Read(./secrets/**)",
"Bash(curl:*)"
]
}
}权限评估顺序：deny → ask → allow。设为deny后文件对Claude"不可见"。
十、Claude Code常见陷阱（Gotchas）
| # | 陷阱 | 表现 | 缓解方法 |
|---|---|---|---|
| 1 | 过早放弃 | "已实现大部分功能，但XX不工作" | 拆分任务为更小单元 |
| 2 | 上下文压缩后变 |
