链载Ai

标题: 从咒语到工程——Claude Code工程实践 [打印本页]

作者: 链载Ai 时间: 1 小时前
标题: 从咒语到工程——Claude Code工程实践

在上一篇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/#ClaudeCode的原始对话记录├──devlogs/#AI主动记录的工作日志├──optimization-history/#分析结果和改进记录└──templates/#优化后的配置模板├──user-claude.md#更新后的用户级配置├──project-claude.md#项目级配置模板└──commands/#命令集

定期执行的改进流程：

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

这种方法的特点：

独立工程：不污染实际项目，专注于工具优化
数据驱动：基于实际使用数据，而非主观感受
长期积累：改进效果需要在后续项目中逐步验证

关键是把每次的问题和解决方案都记录下来，逐步积累成更完善的工程方法。

四、工程方法的规模化

上面说了很多，但实际搭建起来这么一套，一点不比代码开发轻松，而且AI的输出随机性让调试过程更加折磨。如果每个项目、模块都这么写一套是比较痛苦的。

脚手架化的解决方案

这里我尝试的办法是一类技术栈写一套脚手架，无论是复制配置还是新建项目，可以极大化把构建AI开发这套工程方法的效果长期积累。

脚手架的核心价值在于严格对齐技术栈和AI工具。通过预定义的配置和约束，让AI在一个明确的边界内工作，而不是每次都要重新教育它。这种对齐体现在：

技术选型收敛 —— 比如用既定的状态管理方案，不让AI每次都重新选择
上下文复用 —— 经过项目验证的prompt和命令可以直接继承
风格一致性 —— 统一的项目结构和编码规范，减少随机性
经验沉淀 —— 每个项目的改进都能反馈到脚手架，让后续项目受益

团队实践的放大效应

这个办法其实最佳的应用场合应该是在团队内，搭建工程体系和执行，对人的要求是不同的，可以收集相比个人实践更广泛的实际效果反馈。

五、结语

如果说以前觉得开发工作会被重新定义只是一种直觉，现在更多是逐渐看到一条可行的路线了。通过不断的工程化改进，确实有合理的办法让人工干预越来越少，产出的随机性变低。当你发现自己的主要工作变成了"继续"时，那种荒诞感会推着你去思考更彻底的自动化方案。

在这个试来试去不停折腾的过程里，收获了远比写代码本身更强烈的获得感。这种获得感来自于看到一个系统在逐步进化，从需要频繁纠正到能够独立完成越来越复杂的任务。每一次成功的优化，都像是在教会一个极其聪明但需要引导的助手，而这个过程本身就充满了创造的乐趣。

欢迎光临链载Ai (https://www.lianzai.com/)