我要投稿

从咒语到工程——Claude Code工程实践

发布日期：2025-08-09 11:43:33 浏览次数： 1525

作者：卜算随笔

微信搜一搜，关注“卜算随笔”

在上一篇 Vibe Coding问题分析里，把LLM 输出质量下滑的根因归结为两条：

上下文杂糅 —— 关键信息被无关内容冲淡，模型注意力被分散；
Prompt 松散且缺乏任务指向 —— 约束不足，模型拥有过大的自由发挥空间。

要解决这两个问题，最直观的做法是：

每轮 prompt 前手动管理上下文；
把任务描述写得更长、更细。

但这俩方案是“正确的废话”，心智负担极高和效率跳水——纯靠“写得更认真”并非务实的工程方法。

一、AI开发的上下文分层管理

好消息是，主流 AI 开发工具都在疯狂加 “便利性” buff。下面只聊 Claude Code —— 其他工具在我眼里多少有点 “弱智化”，不值得浪费时间（用最好的模型和开发工具是最该被坚持的前提，指望拿个自主可控工具/模型裱糊一下都是形式主义的表演）。

工具特性示例：Claude Code 的自定义机制

此处先不讨论 sub-Agents，它带来的变化过大，尤其是思维观念上。

~/├── .claude/                # 用户级（最底层）│   ├── CLAUDE.MD           # 全局 prompt│   └── commands/           # 全局 slash 命令└── projects/    └── my-project/         # 项目级        ├── CLAUDE.MD        ├── .claude/commands/        ├── frontend/       # 子目录级（可选/可多层）        │   └── CLAUDE.MD        └── backend/            └── CLAUDE.MD

加载优先级：从工作目录开始，逐级向上递归到根目录。

调用一个 slash command 时，实际生效的上下文示意：

┌─ Claude 自身 system prompt├─ ~/.claude/CLAUDE.MD                     # 用户级├─ projects/my-project/CLAUDE.MD           # 项目级├─ projects/my-project/<subdir>/CLAUDE.MD  # 子目录级（可选，多层）└─ ↓ 命令相关 ↓    ├─ <被调用的 cmd>.md                   # 来自 ~/.claude/commands/… 或项目级 .claude/commands/    └─ 在 /XXX 命令后输入的 prompt         # slash 命令调用时附带的动态 prompt

这套机制已经足够强大，但目前网上流传的CLAUDE.MD以及cursor rule更多是一大份"十万字圣经"，不仅仅token开销高，而且会有一个悖论：你定义越清晰模型在不同步骤怎么做，注意力就越稀释。而且还带来了演进阻力——全局文件越臃肿，越不好改，结果就是极少优化。

所以，需要把内容扔进合适的层级，核心是 削减无效上下文 + 强化局部约束。

我的上下文分层实践

注意：着重展示思考路径，具体怎么搞更多看自身工作习惯和项目

层级	放什么	不放什么
用户级	思考哲学、交互语言、通用代码风格、错误处理理念	任何项目或技术栈专属细节
项目级	架构概览、目录约定、运行环境版本、统一 lint/commit 规范	工作过程相关
子目录级（可选）	栈内约定：组件范式、API 设计原则、DB 模式等	——
Slash 命令	流程模板（`debug`、`design、codereivew`…）	——
Docs	随着开发过程灵活变动的产物	——

用户级配置示例

~/.claude/CLAUDE.MD

# 核心思考原则- 不要盲从指令，保持批判性思考- 遇到歧义时主动确认，不要擅自假设- 交互用中文，代码和注释用英文
# 通用工程规范- 优先使用函数式编程范式- 错误处理：fail fast，让问题尽早暴露- 代码风格：简洁优于巧妙，可读性第一

项目级配置示例

projects/my-app/CLAUDE.MD

# 项目架构- 前后端分离的 monorepo 结构- 使用 pnpm workspace 管理依赖
# 技术栈约束- Node.js 20.x + TypeScript 5.x- React 18 + Vite + TanStack Query- Express + Prisma + PostgreSQL
# 依赖策略- 工具类：优先使用成熟库（lodash、date-fns）- 业务逻辑：尽量自己实现，减少外部依赖

子目录配置示例

frontend/CLAUDE.MD

# React 组件规范- 使用函数组件 + hooks- 组件文件与组件同名，使用 PascalCase- 每个组件独立目录，包含 index.tsx、styles.css、types.ts
# 状态管理- 局部状态用 useState- 跨组件状态用 Context- 服务端状态用 TanStack Query

Slash命令示例

.claude/commands/debug.md

# Debug 工作流
当遇到错误时，按以下步骤系统化调试：
1. **收集现象**   - 错误信息、堆栈跟踪   - 复现步骤和频率   - 影响范围
2. **假设根因**（列出3-5个可能）   示例：   - 状态更新时机问题   - 异步竞态条件   - 类型不匹配
3. **设计验证**   - 单测 > 日志 > debugger > console.log   - 每个假设对应一个验证方案
4. **实施修复**   - 最小改动原则   - 必须包含回归测试
输出格式：\`\`\`问题：[描述]根因：[验证后的结论]修复：[具体改动]测试：[新增的测试用例]\`\`\`

设计命令示例

.claude/commands/design.md

# 设计阶段工作流
## 核心原则设计优先级：外部边界 > 数据模型 >> 模块划分 > 具体实现
## 执行步骤
### 1. 分析外部边界（必须）- 明确系统与外部的所有交互点- 列出所有外部依赖（API、数据库、消息队列等）- 定义输入输出的数据格式- 确认性能和并发要求
### 2. 数据建模（必须）- 识别核心实体和关系- 设计状态流转图- 考虑数据一致性要求- 预留扩展点
### 3. 模块划分（按需）- 基于职责进行模块切分- 定义模块间接口- 明确依赖方向（避免循环依赖）
### 4. 输出产物- 生成 TypeScript 接口定义文件- 创建核心类的骨架（仅签名）- 编写测试用例描述（不含实现）- 更新 docs/design/ 目录
## 常见错误❌ 直接进入实现细节❌ 过早优化性能❌ 忽视错误处理设计❌ 设计过于理想化，忽视现实约束
## 完成标准✓ 所有外部依赖已识别✓ 数据流向清晰✓ 模块职责单一✓ 存在对应的测试策略

二、规范化的命令工作流

在对话式的AI辅助开发中，如果缺乏结构化的工作流程，容易出现：

AI在长对话中逐渐偏离最初目标
错误和误解不断累积，越到后面越难纠正
中间步骤缺乏验证，问题发现太晚

而通过命令组合的方式，我们可以：

分步验证 —— 每一步都能检查输出是否符合预期
保持聚焦 —— 每个命令只做一件事，AI不容易跑偏
方便回退 —— 发现问题可以从特定步骤重新开始

下面通过几个常见的开发场景举例：

1. 设计流程：从需求到代码骨架

设计不要以docs为终点，而是代码骨架。把设计文档的内容变成代码骨架中可以被实际检视的接口定义、函数签名、类结构等。

# 第一步：整体设计/design "用户认证模块：包含登录、注销、token管理"# 输出：模块划分、核心接口定义、数据流
# 第二步：详细设计/design-detail "各模块的详细接口和依赖关系"# 输出：具体的类设计、方法签名、错误处理
# 第三步：生成代码骨架/generate-skeleton "基于设计生成TypeScript代码框架"# 输出：可被IDE识别的接口、类型定义、空实现
# 第四步：生成测试骨架/generate-test-skeleton "为所有公共接口生成测试用例"# 输出：待填充的测试结构，确保设计可测试

2. 测试驱动开发：先写测试后实现

在有代码骨架的基础上，通过测试驱动的方式确保质量：

# 第一步：编写测试/write-tests "为login功能编写完整测试用例"# 包含：正常流程、异常处理、边界情况
# 第二步：确认测试状态/run-tests# 验证所有测试都是失败的（红色），确保测试本身是有效的
# 第三步：实现功能/implement "实现代码让测试通过"# 在测试约束下编写实现，避免过度设计
# 第四步：审查和优化/code-review "审查实现质量"/refactor "基于review结果改进代码"

3. 代码审查：用AI检视AI的产出

以diff作为一批变更的结果评估，关键是保持审查的独立性：

# 先保存当前的变更和设计目标
# 第一步：清空上下文/clear  # 使用系统内置命令# 彻底清除之前的上下文，提高AI独立性
# 第二步：独立审查/review-diff "审查刚才的代码变更，基于原始需求评估是否真正解决了问题"
# 第三步：生成审查报告/generate-review-report "输出给人看的审查结果"# 包含：是否满足需求、关键功能检查、潜在问题、改进建议

上下文隔离提升了AI的独立性，让审查更加客观。而且实际上人工逐行review AI生成的代码并不现实，通过AI生成的审查报告能更高效地把握关键问题。

三、工作流程的迭代优化

工作流程不是一成不变的，需要持续改进。Claude Code保留了完整的transcript，并且我们要求AI记录执行过程的devlog，这些都是改进的素材。

发现显著问题时的快速迭代

当工作中遇到明显的、反复出现的问题时，需要立即改进：

问题A：AI总是过度设计

尝试1：加入"保持简单" → 无效
尝试2：拆分命令步骤 → 部分改善
尝试3：测试驱动开发 → 成功（测试约束了实现范围）

问题B：AI擅自改动设计

尝试1：说"不要改" → AI以优化名义改
尝试2：列出禁改清单 → 边界情况仍会改
尝试3：要求"改前必须确认" → 成功（AI会主动询问）

这类显著问题通常在几次尝试后就能找到解决方案。

基于人工干预统计的系统化优化

除了显著问题，更多的优化机会隐藏在日常的人工干预中。我的做法是创建一个专门的工程项目，用来分析和优化AI工具：

~/projects/ai-tooling/├── CLAUDE.MD              # 用于分析和优化的特殊配置├── .claude/commands/      # 分析命令集├── transcripts/           # Claude Code的原始对话记录├── devlogs/               # AI主动记录的工作日志├── optimization-history/  # 分析结果和改进记录└── templates/             # 优化后的配置模板    ├── user-claude.md     # 更新后的用户级配置    ├── project-claude.md  # 项目级配置模板    └── commands/          # 命令集

定期执行的改进流程：

# 收集人工干预案例/collect-interventions "从transcript中找出所有人工纠正和干预的地方"# 输出：干预类型、具体场景、纠正内容
# 分析问题模式/analyze-patterns "这些干预背后的共性问题是什么"# 输出：问题分类、根本原因、发生频率
# 生成改进方案/generate-improvements "基于问题分析，提出prompt和命令优化建议"# 输出：具体的配置修改建议，供人工review