把 Claude Code 调教成专属后端搭档——.claude 配置体系搭建全记录

作者: 熙衍

发表于2026-04-26

更新于2026-06-02

技术工具

AgentClaude CodeSkill开发工具自动化

用 Claude Code 写了一阵子 Django 后端之后，我发现一个尴尬的问题：它很聪明，但它不知道我的项目规范。每次让它写一个 ViewSet，它可能用 FastAPI 的风格；让它写测试，它可能用 unittest 而不是 pytest；让它改代码，改完还得我自己跑一遍 ruff。

更麻烦的是——我有四个 Django 项目在同时维护，规范相似但不完全相同。靠每次手动贴规范文档？太低效了。

于是我开始系统地搭建 .claude 配置体系。两个月下来，这套配置已经变成了一个完整的”AI 后端搭档”系统：自动遵守项目规范、写完代码自动 lint、改完自动跑测试、复杂任务自动委派给专门的子智能体。

这篇文章就是整个搭建过程的完整记录。

---

一、整体架构

四层架构，各司其职：

• 入口层 — 用户输入 Prompt，一切从这里开始
• 配置层 — CLAUDE.md（系统指令）、settings.json（模型/权限）、skill-rules.json（触发规则）
• 执行层 — Hooks（钩子）、Skills（技能）、Agents（子智能体）、Commands（命令模板）
• 数据层 — history.jsonl（对话历史）、session-env（会话快照）、projects（项目关联）

数据流向：

从	到	关系
入口层 → 执行层	Hooks	用户 Prompt 触发钩子事件
入口层 → 执行层	Agents	复杂任务委派给子智能体
入口层 → 执行层	Commands	快捷指令直达命令模板
配置层 → 执行层	Skills / Agents	CLAUDE.md 和 skill-rules.json 约束行为
配置层 → 入口层	模型选择	settings.json 决定使用哪个模型
执行层 → 数据层	history / sessions / projects	Agents 执行结果写入持久化存储
Hooks → Skills	技能激活	钩子系统根据触发规则激活对应技能

核心思路是分层解耦

---

二、CLAUDE.md：给 AI 立规矩

CLAUDE.md 是整个体系的宪法。系统指令告诉 Claude Code：你是谁、你的职责是什么、什么能做、什么不能做。关于我现在的提示词还是需要我去根据工作情况慢慢优化的。

我写的核心条款：

# System: Goal-Driven Coding Agent

你是主控智能体，目标是完成用户当前任务。
只有当用户明确要求实现、修复、重构或修改代码时，才交付代码变更；
如果用户只要求分析、审查或建议，则只输出分析结果。

## 复杂度判断
简单任务：单文件小改动、简单问答、小片段代码
复杂任务：多文件修改、新功能开发、架构调整、调试多步骤错误

## 子智能体职责
- 复述目标和约束
- 拆解任务并制定执行步骤
- 在动手前检查可用 skills 和项目上下文
- 最终报告：修改了哪些文件、如何运行、如何验证

关键设计点：

1. 明确权限边界——“分析”和”修改”是两种完全不同的模式，防止 AI 自作主张改代码
2. 复杂度分级——简单任务主控直接做，复杂任务委派子智能体，避免大材小用
3. 验收标准——子智能体完成后主控必须独立验收，形成质量控制闭环

这一步看似简单，但它是后面所有组件能协同工作的基础。

---

三、settings.json：模型与权限

{
  "env": {
    "ANTHROPIC_BASE_URL": "",
    "ANTHROPIC_MODEL": "",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  },
  "model": "",
  "permissions": {
    "allow": [],
    "deny": []
  }
}

几个关键配置：

• 自定义 API 端点：通过 ANTHROPIC_BASE_URL 指向指定代理
• 模型固定：ANTHROPIC_MODEL 和 model 双重指定，确保不会被回退到默认模型
• 精简流量：DISABLE_NONESSENTIAL_TRAFFIC 关掉非必要的遥测请求
• 权限白名单：allow/deny 列表控制文件系统访问范围，生产环境建议填上具体路径

settings.local.json 留空是为了区分”全局配置”和”机器本地配置”——团队共享同一个仓库时，每个人可以有自己的本地覆盖。

---

四、Skills 技能系统：让 AI 懂你的领域

这是整个体系里最核心、投入最多的部分。Skills 本质上是一组按需加载的领域知识包，通过触发规则自动激活。

4.1 技能清单

目前配置了 29 个技能，按用途分几类：

后端开发：

• backend-python-guidelines：Django/DRF 规范（models → serializers → views → services → tasks → signals）
• tdd：红-绿-重构测试循环
• diagnose：Bug 调试与性能排查

代码质量：

• karpathy-guidelines：减少 LLM 常见编码错误
• improve-codebase-architecture：架构改进建议

前端设计：

• frontend-design、taste-skill、soft-skill、minimalist-skill、brutalist-skill：不同风格的 UI 设计能力
• gpt-tasteskill、stitch-skill：高级动效与排版
• image-to-code-skill、imagegen-frontend-web、imagegen-frontend-mobile：设计稿→代码

工程方法：

• grill-me：方案深度质询
• caveman：极简通信模式（省 token）
• output-skill：防截断完整输出

项目管理：

• to-prd：对话→PRD
• to-issues：PRD→Issue 拆分
• triage：Issue 分类流转

元技能：

• skill-developer：创建新技能的技能
• write-a-skill：技能编写辅助
• find-skills：发现社区技能

4.2 触发规则引擎

skill-rules.json 是技能系统的”大脑”——决定什么时候激活哪个技能：

{
  "skills": {
    "backend-python-guidelines": {
      "type": "domain",
      "enforcement": "suggest",
      "priority": "high",
      "promptTriggers": {
        "keywords": [
          "Django", "DRF", "serializer", "ViewSet",
          "APIView", "model", "service", "Celery",
          "task", "signal", "migration", "ORM"
        ],
        "intentPatterns": [
          "(create|add|implement).*?(api|endpoint|view|serializer|service)",
          "(fix|handle|debug).*?(error|exception|backend|django|drf)"
        ]
      },
      "fileTriggers": {
        "pathPatterns": ["apps/**/*.py", "core/**/*.py"],
        "contentPatterns": [
          "from django", "from rest_framework",
          "models\\.Model", "APIView", "ViewSet"
        ]
      }
    }
  }
}

触发机制分三层：

1. 关键词匹配——用户提到 “Django”、”serializer” 等词时触发
2. 意图模式——正则匹配 “create an API endpoint” 这类意图短语
3. 文件触发——编辑 apps/**/*.py 路径下的文件时自动激活

enforcement: "suggest" 表示建议使用但不强制阻断，相比 "block" 更灵活。

---

五、Agents 子智能体：分工协作

复杂任务不是一个人干的。配置了 10 个专项子智能体，各司其职：

类别	Agent	职责
🔧 代码生成	auto-error-resolver	自动修复 lint 错误
🔧 代码生成	python-error-resolver	行为保持的错误修复
🔍 代码审查	python-code-reviewer	Django/DRF 专项审查
🔍 代码审查	code-architecture-reviewer	架构一致性审查
📐 规划设计	plan-reviewer	方案前置审查
📐 规划设计	refactor-planner	重构策略制定
📐 规划设计	code-refactor-master	执行重构
🧪 测试文档	python-test-writer	pytest 测试编写
🧪 测试文档	documentation-architect	开发者文档
🌐 外部调研	web-research-specialist	技术问题调研

关键 Agent 详解

python-code-reviewer 是我最常用的审查 Agent。它的审查清单非常具体：

### Django/DRF Structure
- Views 保持薄层：请求解析 → 权限 → 序列化器验证 → service 调用 → 响应
- 业务逻辑在 services.py 中
- 序列化器只管验证和表示，不做复杂业务流程
- Celery 任务只传 ID 不传 Model 实例

### Data Integrity
- 多表写入使用 transaction.atomic()
- Migration 匹配 Model 变更
- 避免 N+1 查询

### Error Handling
- 异常要具体，禁止裸 except Exception
- 外部 SDK 故障要打日志并有降级策略

审查输出按严重程度分三级：BLOCKER（运行时错误/数据损坏）→ WARNING（疑似 Bug）→ SUGGESTION（可维护性改进）。这个分级对实际工作效率影响很大——不会因为一堆 SUGGESTION 淹没真正的 BLOCKER。

plan-reviewer 是一个典型的前置防护 Agent。在动手写代码之前，它会：

• 分析方案中提到的所有技术和系统
• 检查数据库 schema 影响
• 映射依赖关系
• 评估替代方案
• 识别风险点

这比写完代码再发现问题要高效得多。

---

六、Hooks 钩子系统：自动化质量门

写完代码不检查等于白写。Hook 系统在关键事件节点自动执行质量检查：

{
  "hooks": {
    "UserPromptSubmit": [{
      "hooks": [{
        "type": "command",
        "command": "skill-activation-prompt.sh"
      }]
    }],
    "PostToolUse": [{
      "matcher": "Edit|MultiEdit|Write",
      "hooks": [
        { "type": "command", "command": "post-tool-use-python-tracker.sh" },
        { "type": "command", "command": "ruff-check.sh" }
      ]
    }],
    "Stop": [{
      "hooks": [{
        "type": "command",
        "command": "stop-pytest-check.sh"
      }]
    }]
  }
}

工作流是这样的：

用户提交 Prompt
    │
    ▼
┌─ UserPromptSubmit ──────────────────────────┐
│  skill-activation-prompt → 推荐相关技能       │
└──────────────────────────────────────────────┘
    │
    ▼
Claude Code 编辑 Python 文件
    │
    ▼
┌─ PostToolUse ──────────────────────────────┐
│  tracker → 记录被编辑的文件                   │
│  ruff check → 自动 lint 检查                 │
└──────────────────────────────────────────────┘
    │
    ▼
任务完成
    │
    ▼
┌─ Stop ─────────────────────────────────────┐
│  pytest → 运行相关测试 → 结果返回用户         │
└──────────────────────────────────────────────┘

实际效果：

• 每次编辑 Python 文件后，ruff 自动跑一遍，有问题当场发现
• 会话结束时自动跑 pytest，不用手动 python -m pytest
• 如果不想跑测试，设 SKIP_PYTEST_CHECK=1 即可跳过

---

七、Commands 命令模板：高频操作一键触发

有些操作很常见但每次都描述一遍很烦。Commands 就是这些操作的”快捷键”：

命令	用途
/dev-docs	生成完整开发方案（含任务分解、依赖分析、时间线）
/dev-docs-update	更新现有方案文档
/lint	对变更文件跑 ruff check + format
/test	对变更 Django app 跑 pytest

比如 /test 命令的逻辑：

1. 识别最近变更的源文件
2. 映射 apps/<app_name>/*.py → apps/<app_name>/tests.py 或 tests/
3. 运行 python -m pytest <target> -q --tb=short
4. 对 Model 变更额外运行 python manage.py check
5. 报告通过/失败数量和失败回溯

这意味着我只需要输入 /test，它就知道该跑哪些测试——不用手动指定路径。

---

八、Plugins 插件系统

插件市场机制允许安装社区维护的功能扩展：

{
  "claude-plugins-official": {
    "source": {
      "source": "",
      "repo": ""
    },
    "installLocation": ""
  }
}

目前主要使用官方插件市场，blocklist.json 用来阻止不想用的插件。插件系统和 Skills 的定位不同——Skills 是”知识注入”，Plugins 是”能力扩展”。

---

九、数据与持久化

.claude 不只是配置，还是整个使用过程的”黑匣子”：

数据	位置	用途
对话历史	history.jsonl	跨会话上下文的”记忆”
会话快照	session-env/<uuid>/	48 个历史会话的环境状态
文件历史	file-history/<uuid>/	91 个文件的变更追踪
Shell 快照	shell-snapshots/	45 个已执行命令的快照
项目关联	projects/<项目名>/	每个项目的会话 .jsonl
配置备份	backups/	10 个 .claude.json 历史版本

这些数据让 Claude Code 能够：

• 跨会话记住之前的对话（不需要每次重新解释项目结构）
• 追踪每个文件的修改历史（谁改的、什么时候改的、为什么改）
• 在多个项目之间切换而不丢失各自的上下文

---

十、实践经验与踩坑

1. Skill 不是越多越好

一开始我装了 30+ 个 skill，结果每次对话都要加载一堆上下文，token 消耗巨大。后来精简了触发规则，让大部分 skill 只在明确匹配时才激活。priority 字段要合理设置——不是所有 skill 都需要 "high"。

2. Agent 需要明确的输入输出契约

早期我让 Agent 做太泛的事情，比如”审查代码”，它不知道该审什么。后来给每个 Agent 写了详细的检查清单和输出格式，效果提升明显。比如 python-code-reviewer 的 BLOCKER/WARNING/SUGGESTION 三级输出格式。

3. Hook 的执行环境要留意

Windows 上 .sh 脚本不直接可执行，需要配套 .ps1 版本。我两个都准备了，通过 node_modules 里的 TypeScript 编译环境来统一执行。

4. settings.json 里的 token 要小心

ANTHROPIC_AUTH_TOKEN 是敏感信息。如果 .claude 目录要共享给团队，记得把 token 放到 settings.local.json 里（.gitignore 掉）。

5. 定期清理

session-env/ 和 file-history/ 会随着使用不断膨胀。我设了定期清理（.last-cleanup 记录上次清理时间），保留最近 30 天的数据，旧的归档或删除。

---

十一、效果总结

搭建这套体系前后的对比：

维度	搭建前	搭建后
代码规范遵循	每次手动贴规范，经常遗漏	自动激活 backend-python-guidelines，95%+ 符合项目风格
Lint 检查	手动跑 ruff，经常忘记	Hook 自动在每次编辑后运行
测试覆盖	基本不写测试	Agent 自动生成 pytest，Stop 时自动运行
方案审查	想到哪写到哪	plan-reviewer 前置审查，减少返工
多项目管理	上下文混乱，规范串台	项目独立 session，各自维护上下文
错误修复	改了 A 坏了 B	auto-error-resolver 机械修复，不改业务逻辑

最重要的变化是：从”我用 AI 写代码”变成了”AI 帮我把代码写好”。以前是我盯着 AI 的输出挑毛病，现在是 AI 在提交之前自己检查一遍。

---

附录：目录结构速查

~/.claude/
├── CLAUDE.md                 # 全局系统指令
├── settings.json             # 模型/权限/API 配置
├── settings.local.json       # 本地覆盖（不提交 git）
├── skill-rules.json          # 技能触发规则引擎
├── config.json               # 扩展配置
├── .last-cleanup             # 上次清理时间
│
├── agents/                   # 10 个子智能体
│   ├── python-code-reviewer.md
│   ├── code-architecture-reviewer.md
│   ├── plan-reviewer.md
│   ├── python-test-writer.md
│   ├── auto-error-resolver.md
│   └── ...
│
├── skills/                   # 29 个技能模块
│   ├── backend-python-guidelines/
│   ├── frontend-design/
│   ├── tdd/
│   ├── diagnose/
│   └── ...
│
├── commands/                 # 4 个命令模板
│   ├── dev-docs.md
│   ├── lint.md
│   └── test.md
│
├── hooks/                    # 钩子脚本 + node_modules
│   ├── skill-activation-prompt.sh
│   ├── ruff-check.sh
│   ├── stop-pytest-check.sh
│   └── ...
│
├── plugins/                  # 插件系统
│   ├── blocklist.json
│   ├── known_marketplaces.json
│   └── marketplaces/
│
├── projects/                 # 项目关联
│   ├── d--code-trplanning/
│   ├── d--code-HexoBlog/
│   └── ...
│
├── sessions/                 # 会话数据
├── session-env/              # 48 个环境快照
├── file-history/             # 91 个文件变更记录
├── shell-snapshots/          # 45 个命令快照
├── backups/                  # 10 个配置备份
└── ide/                      # 78 个 IDE 进程锁

---

如果你也在用 Claude Code 做 Django 开发，这套配置可以作为起点。每个人/每个团队的项目规范不同，但架构思路是通用的：分层解耦、按需激活、自动检查、持续记录。

本作品由 熙衍 于 2026-04-26 00:00:00 发布

作品地址：把 Claude Code 调教成专属后端搭档——.claude 配置体系搭建全记录复制

除特别声明外，本站作品均采用 CC BY-NC-SA 4.0 许可协议，转载请注明来自 熙衍

AgentClaude CodeSkill开发工具自动化