还是Claude Code干活靠谱啊工程化配置与工作流实践

Compound Engineering 方法论原文：https://every.to/chain-of-thought/compound-engineering-how-every-codes-with-agents。是整个工作流最有价值的环节——它将本轮工作的模式、陷阱和决策记录下来，更新到 CLAUDE.md 和 rules 目录中，让下一轮工作站在更高的起点上。CLAUDE.md 是 Cl

Honmaple

401人浏览 · 2026-04-16 09:35:44

Honmaple · 2026-04-16 09:35:44 发布

Claude Code 工程化配置与工作流实践

去掉营销话术，只保留经过实际项目验证的配置方法和工作流。本文所有内容均基于 Claude Code 官方文档、社区最佳实践仓库以及 Compound Engineering Plugin 的实战经验整理。

一、配置体系总览

Claude Code 的配置分为四个层级，优先级从高到低：

层级	文件位置	作用域	典型用途
组织强制	`managed-settings.json`	全局，不可覆盖	安全合规、审计策略
项目共享	`.claude/settings.json`	团队共享（提交至 Git）	统一工具权限、MCP 服务器
项目个人	`.claude/settings.local.json`	个人（git-ignored）	个人偏好、本地路径
全局个人	`~/.claude/settings.json`	所有项目	默认编辑器、全局 Hooks

命令行参数可单次覆盖以上所有配置。

关键原则：settings.json 管理"能做什么"（权限），CLAUDE.md 管理"怎么做"（规范）。两者职责分离，不要混用。

二、settings.json 核心配置

权限管理

权限分为三级：allow（自动放行）、ask（每次询问）、deny（直接拒绝）。合理的权限配置能大幅减少交互摩擦，同时保持安全边界。

{
  "permissions": {
    "allow": [
      "Bash(pnpm test:*)",
      "Bash(pnpm lint:*)",
      "Bash(git diff:*)",
      "Bash(git log:*)",
      "Read",
      "Write(.claude/**)",
      "Edit(.claude/**)"
    ],
    "deny": [
      "Bash(rm -rf:*)",
      "Bash(curl | bash:*)"
    ]
  }
}

上面的配置放行了所有测试和 lint 命令（pnpm test:* 通配符匹配任意参数），但禁止了高危操作。这是一个实际项目中经过验证的安全基线。

MCP 服务器

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-filesystem", "/path/to/project"]
    }
  }
}

MCP 服务器按需引入，不要贪多。一个 memory 服务器加一个文件系统服务器，覆盖了 90% 的日常场景。

Hooks

Hooks 在关键节点自动执行脚本，适合做质量门禁和通知：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write",
        "command": "npx prettier --write $FILEPATH",
        "timeout": 5000
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Bash",
        "command": "python3 scripts/hooks.py post-bash",
        "timeout": 3000
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "command": "afplay /Users/you/sounds/done.mp3"
      }
    ]
  }
}

实际项目中，PreToolUse Hook 做格式化、PostToolUse Hook 记录 token 消耗、Stop Hook 播放提示音——三个 Hook 就够了。

三、CLAUDE.md 编写规范

CLAUDE.md 是 Claude Code 的"项目记忆"。它不是 prompt engineering，是工程规范文档。

结构模板

# 项目名称

## 技术栈
- 框架：Next.js 15 (App Router)
- 包管理：pnpm
- 测试：vitest + testing-library
- 代码规范：biome（非 eslint）

## 常用命令
- `pnpm dev` — 启动开发服务器
- `pnpm test` — 运行全部测试
- `pnpm test:path/to/file.test.ts` — 运行单个测试
- `pnpm lint` — 代码检查与自动修复

## 代码规范
- 使用 TypeScript strict 模式
- 组件文件名使用 PascalCase
- 工具函数放在 `src/utils/` 下
- 禁止 any 类型，使用 unknown 替代

## 架构约束
- API Route 必须放在 `src/app/api/` 下
- 数据库操作统一通过 Prisma，禁止裸 SQL
- 组件禁止直接访问环境变量，通过 config 层传递

## 测试要求
- 新功能必须附带测试
- 测试文件与源文件同目录
- 使用 describe/it 组织，禁止 test.skip

关键规则

控制在 200 行以内。超过 200 行 Claude Code 的遵从度会明显下降。将低频规则拆到 .claude/rules/ 目录下的独立 .md 文件中，Claude Code 会自动加载。
写约束，不写废话。"本项目是一个现代化的 Web 应用"没有信息量。"禁止 any 类型"有信息量。
命令必须可直接复制执行。不要写"运行测试命令"，直接写 pnpm test。

四、Skills 与 Subagents

Skill 定义

Skill 是可复用的指令模块，放在 .claude/skills/ 目录下：

---
name: create-api-route
description: 创建新的 API Route，包含类型定义和错误处理
argument-hint: "[route-path]"
allowed-tools: Read, Write, Edit, Glob
---

根据用户提供的路由路径，创建完整的 API Route 文件。

步骤：
1. 在 `src/app/api/{path}/route.ts` 创建文件
2. 定义 Request/Response 类型
3. 实现错误处理中间件
4. 在路由注释中标注 HTTP 方法

Skill 有两种调用方式：通过 /create-api-route 手动触发，或在 description 中写明触发条件让 Claude Code 自动调用。

Subagent 编排

Subagent 适合封装需要独立上下文的任务（如代码审查、文档生成）。定义在 .claude/agents/ 下：

---
name: code-reviewer
description: PROACTIVELY review code changes before merging
tools: Read, Glob, Bash
disallowedTools: Write, Edit
model: sonnet
maxTurns: 15
---

审查当前分支相对于 main 分支的所有变更。

关注点：
1. 类型安全
2. 错误处理完整性
3. 性能隐患
4. 安全漏洞
输出格式：按严重程度排列的发现列表。

核心注意：Subagent 不能通过 bash 命令调用其他 subagent，必须使用 Agent() 工具。在定义中避免使用"启动"、"运行"等模糊动词，明确写出允许的工具列表。

五、Compound Engineering 工作流

Compound Engineering Plugin 提供了一套经过实战验证的工作流框架，核心理念是：每个工程单元应该让后续单元更容易，而不是更难。

工作流循环

/ce:brainstorm → /ce:plan → /ce:work → /ce:review → /ce:compound → 重复

命令	职责	产出物
`/ce:brainstorm`	需求探索，交互式 Q&A 精炼想法	需求文档
`/ce:plan`	将需求转化为可执行的技术方案	实施计划（含文件清单）
`/ce:work`	基于 plan 执行，使用 worktree 隔离	代码变更
`/ce:review`	多 agent 交叉审查	审查报告
`/ce:compound`	将经验沉淀为可复用知识	模式文档、CLAUDE.md 更新

安装与初始化

# Claude Code
/plugin marketplace add EveryInc/compound-engineering-plugin
/plugin install compound-engineering

# 初始化（检查环境、安装依赖、引导配置）
/ce-setup

该插件还支持 Cursor、Codex、OpenCode、Gemini CLI 等多种编辑器和 Agent 工具，通过 CLI 转换格式即可使用。

实践要点

/ce:brainstorm 是主入口。它会通过交互式提问将模糊想法精炼为结构化需求文档。当任务简单到不需要完整仪式时，它会自动跳过中间环节。/ce:compound 是整个工作流最有价值的环节——它将本轮工作的模式、陷阱和决策记录下来，更新到 CLAUDE.md 和 rules 目录中，让下一轮工作站在更高的起点上。

六、日常操作清单

以下是经过多个项目验证的高频操作模式：

开始新任务

开一个新会话（不要在长会话里切换任务）
复杂任务先用 Plan Mode（ Shift+Tab 两次）列出步骤
让 Claude Code 先读 CLAUDE.md，确认上下文
上下文用到 50% 时手动 /compact

代码审查

切到功能分支后启动 review subagent
subagent 只分配 Read/Glob/Bash 权限，禁止写操作
审查完成后人工确认再合并

多步骤任务

让 Claude Code 先输出任务清单
逐步确认后再执行（不要一次全部放行）
每完成一个关键步骤做一次 git commit
出错时不要在同一会话反复修正，新开会话带上 commit history

避免

不要在单个会话中处理超过三个不相关任务
不要在 CLAUDE.md 中写超过 200 行（拆到 rules/ 目录）
不要给 subagent 分配模糊的工具权限（明确列出 allowlist）
不要跳过 /compact（上下文膨胀后质量直线下降）

参考资源

Claude Code 官方最佳实践：https://code.claude.com/docs/en/best-practices
Compound Engineering Plugin：https://github.com/EveryInc/compound-engineering-plugin
Claude Code 最佳实践参考仓库：https://github.com/shanraisshan/claude-code-best-practice
Compound Engineering 方法论原文：https://every.to/chain-of-thought/compound-engineering-how-every-codes-with-agents