Claude Code 实战知识地图（2026年版）

单人开发 SaaS（FastAPI + Vue3 + pnpm monorepo）场景下，系统性掌握 Claude Code 的完整指南。信息基于官方文档（截至 2026-05），直接可用于生产。

1. 核心能力分层

1.1 访问方式与应用场景

CLI（本地）：日常开发、快速迭代 → 全权限、本地执行、低延迟
VS Code 扩展：IDE 内联工作 → 直接编辑体验、快速提交
Desktop App：专注编程、全屏工作 → 沉浸式、集中注意力

建议：单人开发用 CLI + VS Code，保持最大灵活性和速度。

1.2 工作模式（Shift+Tab 切换）

模式	文件编辑	Shell 命令	何时用
Default	每次询问	每次询问	常规开发
Auto-accept	自动	信任的指令自动	信任的工具链
Plan Mode	读权限	查询权限	分析复杂问题

单人开发建议：小改动用 Auto-accept（提速 30%）→ 跨模块用 Plan Mode（先设计再实施）

1.3 模型选择

Opus 4.7（默认）：1M context、最强推理 → 架构设计、多模块重构
Opus 4.6 (Fast)：200K context、便宜 60%、快 30-40% → 单文件修改、测试修复

在 .claude/settings.json 中配置或 /model 临时切换

2. 上下文管理与文件分层（最关键）

2.1 CLAUDE.md 五层金字塔（从广到窄）

1️⃣ ~/.claude/CLAUDE.md             全局（跨所有项目）
2️⃣ ~/.claude/rules/*.md             用户规则（跨所有项目）
3️⃣ ./CLAUDE.md                      项目级（可 git 提交）
4️⃣ ./.claude/rules/backend.md       子目录规则（按 paths 触发）
5️⃣ ./CLAUDE.local.md                个人沙箱（本机，.gitignore）

关键原则：
- 长度：每个文件 < 200 行（超过会减少遵循度）
- 结构：用 Markdown 标题分组，便于扫描
- specificity：具体规则 > 模糊建议

PackCompliance 推荐结构：

./.claude/CLAUDE.md 包含：
- 三端架构约束（P/T/C，JWT tenant_id）
- 后端分层（controller/service/dao）
- 多租户规则（所有查询必须带 tenant_id）
- 接口响应统一格式
- 命令速查

./.claude/rules/backend.md 包含：
- 路径匹配：paths: "backend/*/.py"
- FastAPI 约定（路由位置、测试分层）

2.2 Context 窗口分布（1M token）

启动时消耗：系统提示 5K + CLAUDE.md 30K + rules 20K + 会话历史 300K + 当前文件 200K = 剩余 435K

当 >800K 时，auto-compact 启动。运行 /context 看占用，/compact 压缩

2.3 文件导入（@语法）

## 架构设计
@文档/C技术文档/PackCompliance_TAD_v2_backend.md

## 前端约定
@./frontend/CLAUDE.md

启动时自动展开引用文件内容

3. Skills（复用工作流的核心）

3.1 何时写 Skill

写的信号：同一指令重复 3 次、5 步以上的工作流、需要动态数据注入、跨项目复用
不写：一次性琐碎指令、CLAUDE.md 的静态规则、纯参考内容

3.2 三级 Skill 组织

~/.claude/skills/          个人全局（所有项目）
./.claude/skills/          项目级（本项目）
  ├── backend-test/SKILL.md（必需）
  ├── fixtures.json
  └── templates/

3.3 完整 Skill 示例（后端测试）

---
name: backend-test
description: 运行后端测试并报告失败用例
when_to_use: "测试、pytest、单元测试"
disable-model-invocation: false
allowed-tools: Bash(pytest:*) Read
model: claude-opus-4-6
paths: "backend/**"
---

## 后端测试流程

cd PackCompliance && pytest packages/backend/tests -v --tb=short

关键检查：
- [ ] 多租户隔离（tenant_id 过滤）
- [ ] API 响应格式统一
- [ ] 数据库迁移正向兼容

调用：/backend-test 或自动触发（Claude 看到后端改动 + "测试" 关键词）

3.4 动态数据注入（!`command`）

---
name: code-review
context: fork
agent: Plan
---

## 当前变更

Diff 摘要：
!`git diff --stat HEAD`

多租户检查：
!`git diff HEAD | grep -E "tenant_id|TENANT" || echo "（无相关改动）"`

4. Hooks（自动化的关键）

4.1 五类 Hook 事件

事件	触发时机	用途
SessionStart	会话开始	注入环境信息
PreToolUse	执行前	拦截危险操作
PostToolUse	执行后	自动 lint/format
UserPromptSubmit	用户按 Enter	前置验证
Stop	会话结束	清理/提交

4.2 两个最有用的 Hook

Hook 1：PostToolUse（编辑后自动 lint）

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "if": "Edit(**/*.py)",
            "command": "/bin/bash",
            "args": ["-c", "python -m ruff check --fix backend/"],
            "statusMessage": "运行 ruff lint..."
          }
        ]
      }
    ]
  }
}

Hook 2：PreToolUse（拦截 force push）

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(git push --force*)",
            "command": "/bin/bash",
            "args": ["-c", "echo '{\"hookSpecificOutput\": {\"permissionDecision\": \"deny\"}}'"]
          }
        ]
      }
    ]
  }
}

配置优先级：项目 .claude/settings.json > ~/.claude/settings.json > Skill 内 hooks

5. Subagents（并行工作的利器）

5.1 何时用

用的信号：大量 grep/read 结果污染 context、独立子任务可并行、需要不同权限/模型
不用：简单修改、频繁交互、任务太小

5.2 内置 Agent 类型

Explore：只读工具 → 代码分析、架构审查
Plan：读 + 规划 → 拆解需求、设计方案
general-purpose：全部工具 → 实际开发任务
code：全部 + 代码优化 → 代码生成、重构

5.3 自定义 Subagent（前端工程师）

# ./.claude/agents/frontend-specialist.md

Name: FrontendSpecialist
Description: Vue3 + Pinia 前端专家，处理 T 端页面开发

## 职责
专注 T 端（租户后台）开发。禁止修改后端、数据库、环境变量。

## 开发流程
1. 读 HLD 确认页面结构
2. 检查组件库（CLD.pen）
3. 构建页面 → 组件拆分 → 样式调整
4. 本地测试（http://localhost:3000）
5. 提交 PR

@CLAUDE.md
@packages/t-end/CLAUDE.md

在 skill 中调用：

---
name: t-end-feature
description: 为 T 端开发新功能
agent: FrontendSpecialist
context: fork
---

基于 HLD，开发：$ARGUMENTS

6. MCP 服务集成

6.1 推荐装的 MCP（PackCompliance）

Server	用途	节省
filesystem	文件操作扩展	高级搜索、批量
github	PR/Issue 管理	自动读 Issue → 编代码
postgres	数据库查询	直接查数据、生成迁移
pencil	设计稿管理	读取原型、同步设计

不装：slack、discord、notion（信息溅射、容易过期）

6.2 配置与成本

在 settings.json 注册，运行 /mcp 看成本。大型 MCP 用 tool search 按需加载

7. 完整工作流：从需求到提交（三段式）

7.1 第一段：分析（Plan Mode）

/plan

"实现多租户产品管理模块：
- 列表（分页、搜索、多租户隔离）
- 详情、新建/编辑、删除（软删除）
- 涉及 P 端 + T 端

分析需求、数据库设计、接口、前端页面。"

# Claude 在 Plan Mode（只读）：
# 1. 读 HLD 理解架构
# 2. 学习现有 product module
# 3. 生成方案 + 多租户检查点
# 4. 列出决策点

输出：设计方案 + 确认清单，不执行代码

7.2 第二段：实施（Auto-accept Mode）

/config  # 切换 auto-accept
"按方案实施。后端先。"

# Claude 执行：
# 1. Alembic 迁移
# 2. product/controller.py（CRUD）
# 3. product/service.py（业务逻辑 + tenant_id）
# 4. product/dao.py（数据库）
# 5. pytest 验证
# 6. （自动 lint hook）
# 7. 提交 commit

7.3 第三段：审查

/review          # 自动代码审查 + 测试
/security-review # 多租户风险 + 权限控制 + SQL 注入

8. 提效黑科技（SaaS 开发）

8.1 后端接口 → 前端类型自动同步

/frontend-types

# Skill 从后端 controller 自动提取类型
# 生成 packages/shared/src/types/api.ts

8.2 多端 Monorepo 并行开发

/batch

"修改 DataTable.vue：
- P1：行级权限控制
- P2：导出 CSV
- T1：租户数据权限

3 个并行 agent 处理"

# /batch 自动创建 worktree 并行，完成后合并

8.3 模糊需求快速分解

/claude-mem:make-plan

"分解 '优化产品合规审核流程'为具体任务清单"

# 生成：第一阶段（数据库迁移）→ 第二阶段（后端）→ 第三阶段（前端）→ 第四阶段（测试）

/claude-mem:do  # 按顺序执行各阶段

9. 反模式与避坑指南

9.1 Top 5 常见误用

误用	症状	解决
不更新 CLAUDE.md	同样指令重复说 3 次	每周整理，加进 CLAUDE.md
Skill 写太长	每次加载浪费 context	Skill < 300 行；长内容放 supporting
滥用 subagent	微任务都 fork	仅 >1K tokens 的任务用 subagent
MCP 装太多	启动加载 20+	常用 3-4 个，其他按需
忘记 --add-dir	跨项目共享看不见	`claude --add-dir ~/rules`

9.2 多租户陷阱（必读）

# ❌ 坏：忘记 tenant_id 过滤（数据泄露！）
@router.get("/products")
async def list_products(db: AsyncSession):
    return db.query(Product).all()

# ✓ 好
@router.get("/products")
async def list_products(
    db: AsyncSession,
    current_user: User = Depends(get_current_user)
):
    return db.query(Product).filter(
        Product.tenant_id == current_user.tenant_id
    ).all()

CLAUDE.md 检查清单：

## 多租户安全检查

新增 API 时验证：
- [ ] 所有 SELECT 都有 WHERE tenant_id = ?
- [ ] 所有 UPDATE/DELETE 都有 WHERE tenant_id = ?
- [ ] JWT 中 tenant_id 不可绕过/伪造
- [ ] 禁止跨租户 JOIN

9.3 其他常见坑

坑 1：编辑后忘记跑测试 → Hook 自动 pytest
坑 2：每次重复解释架构 → /memory 检查，补充 auto memory
坑 3：Context 爆炸越来越慢 → /context 看占用，/compact 压缩

10. 性能优化检查清单

每周一次：
- □ /context：看占用（目标 <500K）
- □ /memory：检查 auto memory
- □ /mcp：看成本，禁用不用的
- □ /skills：禁用低频 skill

每次大功能完成：
- □ /review：自动代码审查
- □ /security-review：安全审查（多租户、权限）
- □ git log --oneline：提交清晰度

月度维护：
- 整理 CLAUDE.md（删过时规则）
- 清理 .claude/rules/（合并相似）
- 更新 CLAUDE.local.md（新测试数据）

总结表：需求 → 工具映射

需求	工具	用法
日常 bug 修复	Default Mode	`claude` 描述后迭代
复杂架构设计	Plan Mode	`Shift+Tab` 两次，分析
自动 lint/format	PostToolUse Hook	编辑后自动运行
并行开发多功能	/batch	3+ 并行 agent
拆解模糊需求	/claude-mem:make-plan	生成任务清单
隔离大量查询	Subagent (Explore)	减少污染 context
后端 API → 前端类型	/frontend-types	自动生成接口
数据库操作	PostgreSQL MCP	直接查 + 迁移
质量保证	/review + /security-review	提交前检查

进阶资源

官方文档：
- https://code.claude.com/docs/en/how-claude-code-works.md（架构）
- https://code.claude.com/docs/en/memory.md（CLAUDE.md）
- https://code.claude.com/docs/en/skills.md（Skills）
- https://code.claude.com/docs/en/hooks.md（Hooks）
- https://code.claude.com/docs/en/sub-agents.md（Subagent）

你的项目：
- ~/.claude/CLAUDE.md（全局）
- ./CLAUDE.md（项目）
- ./README.md（启动）

核心洞察：Claude Code 的价值 80% 来自 CLAUDE.md + Hooks + Skills 三件套的组织，不来自 Claude 本身。打磨这三个，效率提升 10 倍。

作者：张少楠