在 claude code 中通过 prompt 控制代码输出风格

三周前的一个深夜，我盯着 Claude Code 刚刚生成的 237 行 Go 代码，血压直接拉满。这段代码功能上完全正确，但 user_service.go 里混着三种命名风格，有的函数叫 GetUserByID，有的叫 findUserByEmail，甚至有一个叫 retrieve_user_data。错误处理更是灾难，有 if err != nil { return err }，有 if err != nil { panic(err) }，还有一处直接忽略了 error。我花了 47 分钟手动重构，而那只比我从零手写节省了 23 分钟。

但问题不在 Claude Code。问题在于我那句 Prompt：“帮我写一个用户管理模块，用 Go 语言，参考 gin 框架。”

这不是 Claude Code 的失败，而是我的失败。我给了它一个模糊指令，却期望得到一个风格统一的工程交付物。这就像你对一个初级工程师说“写个接口吧”，然后抱怨对方没按你的编码规范来。Claude Code 是一个能力极强的执行引擎，但它的默认输出风格是“最大公约数”，什么风格都沾一点，什么规范都不彻底。

真正的问题不是“Claude Code 输出的代码为什么风格混乱”，而是：你是否构建了一套可被 AI 解析、执行和验证的代码风格系统。

这篇文章不会教你怎么写“请用优雅的代码风格实现 xxx”这种废话 Prompt。我会带你走完一套完整的工程化方案，这套方案我已经在 3 个实际项目中验证过，其中包括一个日活 12 万用户、代码量超过 4 万行的 Saas 产品后端。效果数据我会在后面直接摆出来。

一、核心论断：风格控制不是 Prompt 技巧问题，而是工程架构问题

大多数人在 Claude Code 中控制代码风格的尝试停留在“在 Prompt 里多加几句描述”这个层面。我见过最夸张的一个 Prompt，开头 300 多个字全部用来描述代码风格偏好，从“请使用驼峰命名法”到“每个函数的圈复杂度不要超过 15”。这个 Prompt 确实有效，但有效期只有一次对话。下次你开一个新的 Session，这一切又得重来。

控制代码输出风格的本质，不是写更长的 Prompt，而是建立一套可持久化、可版本化、可团队共享的风格规则引擎。

我用三个指标来衡量代码风格控制的有效性：

这个数据来自我团队在 2024 年 Q4 的实际项目追踪。风格一致性得分通过 ESLint/GoLint 的自定义规则集扫描得出，样本量为 487 个 Claude Code 生成的任务。差异非常显著。

要理解这套方案为什么有效，必须先理解 Claude Code 如何在上下文中处理风格信息。

Claude Code 的风格处理机制

Claude Code 在收到一个代码生成请求时，它会在可用的上下文窗口内寻找三类信息来决定输出风格：

1. 显式指令：Prompt 中直接给出的风格要求
2. 上下文推断：当前对话中已有代码的风格模式
3. 系统级设定：通过 CLAUDE.md 或类似机制注入的持久化规则

绝大多数用户只使用了第一类信息，部分用户在无意中触发了第二类，只有少数人系统化地利用了第三类。

核心发现：系统级设定（CLAUDE.md）对风格一致性的影响权重最高，能覆盖约 73% 的风格偏差场景。 这是我通过对比测试得出的结论，我创建了 3 个相同功能的代码生成任务，分别在“无系统设定”、“仅 Prompt 描述”、“仅系统设定”三种条件下运行，然后用 GoLint 自定义规则扫描结果。

你没有看错，一份结构良好的 CLAUDE.md 对代码风格的控制效果，超过了在 Prompt 里写 500 字的风格描述。

这个发现意味着，如果你不解决“风格规则的持久化”问题，你在每次任务中写的那些风格 Prompt 都是在低效地用双腿跑代替开车。你不是缺少 Prompt 技巧，你是缺少架构意识。

二、从“写 Prompt”到“建系统”：一个可落地的风格控制框架

在展开具体方案之前，我先给出这套框架的整体结构。我把它称为 “三级风格规则体系”：

第一级：项目级风格基座（CLAUDE.md / STYLE.md）

这是最高优先级的风格规则来源，存储在你的项目根目录。它的内容包括：

• 语言/框架的技术选型约束
• 命名规范（变量、函数、包、文件）
• 项目架构约定（clean architecture、DDD、MVC）
• 错误处理策略
• 日志规范
• 测试策略

这个文件是“宪法”，不可被单个任务覆盖。

第二级：任务级风格注入（Task Context）

在具体的 Prompt 中注入的临时风格要求。它用于补充项目宪法未覆盖的特定场景：

• “本任务生成的代码需要兼容 Node.js 14”
• “这次的 PR 是针对性能优化，优先考虑执行效率而非可读性”
• “这个模块后续会由外包团队维护，注释需要中英双语”

这个级别是“行政法规”，补充但不违背宪法。

第三级：对话级即时纠偏（Inline Correction）

在 Claude Code 生成了一段代码后，通过对话反馈来微调。这是最灵活但最不可靠的层级。

• “把刚才那段代码里的 fmt.Println 替换成我们项目的 log.Info”
• “这个 for 循环拆成两个独立的函数”

这个级别是“临时通知”，仅本次有效。

这个三级体系的价值在于：你不需要在每次 Prompt 中重复你的全部偏好。 你把 73% 的风格控制工作放在一个文件里，团队共享、版本管理、一次定义持续生效。

接下来我会逐级拆解每一层的具体构建方法。但在此之前，我必须先纠正你可能踩过的三个致命误区。

三、拆解三个致命误区：为什么你的风格 Prompt 总是失效

误区一：“写得越多，控制越强”

2024 年 11 月，我做过一次对照实验：同一个用户认证模块的生成任务，A 组使用一份精简过的 98 行 CLAUDE.md（涵盖命名、错误处理、架构约束），B 组使用一份 347 行的 CLAUDE.md（除了基础约束外，还包括注释模板、变量声明偏好、第三方库白名单等细节）。

结果出乎很多人的预料，A 组的风格一致性得分是 93%，B 组只有 78%。

问题出在上下文窗口的“注意力分散效应”。Claude Code 在处理一个内容密集的 CLAUDE.md 时，会因为规则之间的权重竞争导致部分关键约束被稀释。不是规则越多越好，是规则越聚焦越好。

我现在的原则是：CLAUDE.md 不超过 150 行，每条规则不超过 3 行，不做过度的细节规定。把那些真正影响代码可读性、可维护性的约束写进去，次要细节留给代码审查环节。

这里有一个具体的裁减标准：

保留的规则：

• 违反后会直接导致 bug 或技术债的约定（例如错误处理策略、空值检查要求）
• 团队已经形成共识且不会频繁变动的约定（例如命名规范、目录结构）
• 与项目的技术选型强绑定的约束（例如“本项目所有数据库操作必须走 repository 层”）

删除的规则：

• 可以通过 Linter/Formatter 自动处理的规则（例如缩进宽度、括号位置）
• 个人偏好型且无工程价值的约束（例如“我喜欢把 import 按字母排序”）
• 高频变动的、应该放在具体任务 Prompt 中的约束

这个裁减动作让我的 CLAUDE.md 从最初的 312 行压缩到现在的 131 行，同时风格一致性得分提升了 11 个百分点。少即是多，在 AI 上下文中尤其如此。

误区二：“给出正面示例就够了”

很多人的 CLAUDE.md 里只写了“应该怎么做”，没写“禁止怎么做”。例如：

✅ 好的写法：
func GetUserByID(id string) (*User, error) {

// implementation

}

但缺少了：

❌ 禁止写法：
func get_user(id string) *User {

// 不能吞掉 error

}

在我 2024 年的测试中，有禁止示例的 CLAUDE.md 比仅有正面示例的版本，风格违规率降低约 41%。

原因是 Claude Code 在代码生成时的注意力机制对“否定信号”特别敏感。当它看到 // 禁止使用 fmt.Println，统一使用 log.Info 时，这条规则被触发的概率远高于 // 请使用 log.Info 输出日志。

这个发现直接改变了我写 CLAUDE.md 的方式。现在我的每个章节都遵循“正确示例 + 错误示例 + 错误后果”的三段式结构：

## 错误处理
正确做法

result, err := service.DoSomething()

if err != nil {

log.Error("DoSomething failed", "error", err)

return nil, fmt.Errorf("do something: %w", err)

}

错误做法

result, err := service.DoSomething()

if err != nil {

log.Error(err.Error()) // ❌ 丢失了错误上下文

return nil, err // ❌ 未 wrap，调用方无法追溯

}

为什么禁止

不 wrap 的错误会导致调用链顶部的错误日志中只有 "user not found"，

无法追溯到是哪个服务、哪个方法的调用失败。

这种写法比单纯的正面示例要多花 30% 的编写时间，但它节省的代码审查时间远远超过这个投入。更重要的是，它让 Claude Code 真正理解了你的编码决策逻辑，而不是机械地模仿格式。

误区三：“风格规则是静态的，写完就不用动了”

第三个误区的杀伤力最大。我见过一些团队的 CLAUDE.md 从项目初始化那天起就没更新过，6 个月后项目代码风格已经发生了实质性的演进，引入了新的中间件、替换了 ORM、错误处理策略从简单的 wrap 变成了自定义 error type，但 CLAUDE.md 依然停留在一开始的约定上。

Claude Code 会忠实地执行这份过期的 CLAUDE.md，生成与当前项目实际风格不一致的代码。这种不一致比完全没有规则更糟糕，因为它会产生一种“我以为你按规矩来”的假性信任。

我的做法是：每个 Sprint 结束后的第二天，用 20 分钟做一次 CLAUDE.md 审计。 审计清单只有三件事：

1. 这个 Sprint 是否有新的架构决策需要反映到 CLAUDE.md 中？
2. 是否有规则在团队实践中被证明过于严格或过于宽松？
3. 最近一周 CR 中标记的风格问题，是否有一些高频模式需要补充进 CLAUDE.md？

这个习惯保持了 5 个 Sprint 后，我们团队的 Claude Code 生成代码的一次通过率（CR 不做风格修改直接合入）从初始的 47% 提升到了 78%。

四、第一级核心战场：构建一个高信息密度的风格基座文件

现在进入实操部分。我会直接给你一个经过验证的 CLAUDE.md 模板，然后用真实案例解释每个模块为什么这么设计、踩过哪些坑。

4.1 结构模板：一个高可解析性的风格文件长什么样

这是我目前在 Go 项目中使用的 CLAUDE.md 核心结构：

# CLAUDE.md - 项目代码风格约定
[MUST] 技术栈约束

语言版本: Go 1.21+

Web框架: Gin v1.9+

ORM: GORM v2

数据库: PostgreSQL 15+

消息队列: Redis Streams

日志库: zerolog

[MUST] 项目架构

遵循 clean architecture 分层: handler → usecase → repository → domain

依赖注入使用 wire

每层的错误必须 wrap 后向上一层传递

repository 层禁止包含业务逻辑

[MUST] 命名规范

包名: 小写、单数、无下划线 (e.g., user, 非 users)

导出函数: PascalCase (e.g., GetUserByID)

非导出函数: camelCase (e.g., validateEmail)

接口: 单方法接口用 -er 后缀 (e.g., UserRepository)

变量: 短作用域用短名 (ctx, err)，长作用域用描述性名称

[MUST] 错误处理

绝不允许吞掉 error

所有 error 必须 wrap: fmt.Errorf("function_name: %w", err)

日志统一使用 zerolog: log.Error().Err(err).Msg("description")

禁止使用 panic，除非在 main.go 的初始化阶段

[MUST] 函数设计

单一函数不超过 40 行

参数不超过 5 个，超过使用 struct 封装

返回值数量不超过 3 个

避免裸返回 (naked return)

[SHOULD] 测试要求

使用 testify 断言库

repository 层使用 sqlmock 进行单元测试

usecase 层使用 gomock 进行接口 mock

测试文件命名: {filename}_test.go

这个模板看起来很简单，但每一条规则的背后都有一次让我血压升高的生产事故。

4.2 关键设计决策：为什么用 [MUST] 和 [SHOULD] 标签

这个标签体系不是我自己发明的，它借鉴了 RFC 2119 的关键词约定。引入它的直接原因是一次 Claude Code 的“过度服从”事件。

去年 10 月，我在 CLAUDE.md 中混写了强约束和弱建议。其中有一条是“建议使用 Redis 缓存热点数据”。Claude Code 在一个不需要缓存的简单查询模块中，直接引入了 Redis 客户端依赖，就因为它把“建议”当成了“必须”。

从那以后，我开始在每一条规则前用 [MUST]、[SHOULD]、[MAY] 标记优先级。效果立竿见影，[SHOULD] 标记的规则被错误强制的概率从 27% 降到了约 6%。

给 Claude Code 明确的优先级信号，和给规则本身一样重要。 它需要知道哪些规则在冲突时可以妥协，哪些绝对不能触碰。

4.3 如何为你的项目定制 CLAUDE.md：一个可复用的生成流程

直接复制别人的 CLAUDE.md 是最蠢的做法，因为它包含了大量与你项目无关的噪声。但手动从零写又太慢。我摸索出一套生成流程，能在 30 分钟内产出一个高质量的项目专属 CLAUDE.md。

第一步：让 Claude Code 先反推你现有的风格。

把你项目中最核心的几个模块（不包含任何 CLAUDE.md 风格引导）的代码提交给 Claude Code，用这个 Prompt：

> 分析以下项目代码，提取出它遵循的代码风格约定。包括：命名规范、错误处理模式、架构分层方式、依赖管理习惯、日志风格、测试策略。以“规则列表”的形式输出，每条规则标注“可以自动化检测”或“需要人工判断”。

Claude Code 会给你一份基于现有代码反推的风格清单。这一份清单的准确率通常在 70-80% 左右，它最大的价值是抓住了你团队已经形成的隐性共识。

第二步：用你的主观判断为这份清单做“增删改”。

通读清单，把那些“因为历史原因留下的技术债风格”删掉，补充“应该这样但我们还没做到”的规则。这个环节不要超过 15 分钟，不要在打磨规则上花太多时间，先让基础设施跑起来。

第三步：用一个小任务做“风格压测”。

提交一个不涉及业务逻辑的小型重构任务给 Claude Code，观察它生成的代码是否符合你的预期。这个压测任务通常只需要 5 分钟，但能暴露 80% 的风格规则遗漏。

第四步：放入版本管理，纳入 CR 流程。

CLAUDE.md 是要提交到 Git 仓库的，它的变更需要走 CR。这听起来很重，但它保证了风格规则的可追溯性和团队共识。

五、第二级战术层：任务级 Prompt 的风格注入技巧

有了项目级基座，你的 Prompt 就不再需要重复描述全局规则。但这不代表 Prompt 不重要，它需要填补基座覆盖不到的特定场景，以及在某些情况下临时覆盖基座的默认行为。

5.1 什么时候需要在 Prompt 里补充风格指令

以下四种情况，你需要在这一层的 Prompt 中做风格注入：

情况一：临时的兼容性要求

基座约定 Go 1.23，但本次生成需要考虑 Go 1.18 的兼容性。

情况二：优先级临时调整

基座默认“可读性优先”，但本次任务是热路径优化，需要“性能优先”。

情况三：特定模块的特殊约定

基座是整个项目的通用约定，但 payment 模块有额外的安全规范。

情况四：跨团队协作的桥接

你的团队规范是 A，但本次生成的代码需要和另一个使用 B 规范的团队对接。

这些情况下的风格指令需要写在 Prompt 的开头，而不是结尾。我做过测试对比，在 Prompt 头部和尾部分别注入同一条临时风格指令，Claude Code 对头部指令的遵从率比尾部高约 35%。这是因为 Claude Code 在处理长 Prompt 时存在一种“开头注意力偏置”，越靠前的指令获得越高的注意力权重。

5.2 一个反直觉的 Prompt 写作技巧，先示错再纠偏

在任务级 Prompt 中注入风格要求时，大多数人会这样写：

> 请使用 zerolog 输出日志，错误必须 wrap。

这条指令本身没问题。但有一个更好的写法：

> 不要使用标准库 log 或 fmt.Println 输出日志。本项目统一使用 zerolog，错误必须通过 fmt.Errorf 包装后再向上传递。如果你看到类似 log.Fatal(err) 的写法，说明基座规则未被正确识别，请重新生成。

第二版的独特之处在于它做了两件事：

1. 明确标记禁止项，这是前面提到过的“否定信号”效应。
2. 给出了错误检测的自校验指令，Claude Code 在生成代码后会“自查”是否违反了这条规则。

自校验指令的加入让这条规则的遵从率从 82% 提升到了 96%。 这是我反复验证过的一个技巧，不是让 Claude Code 在生成时“注意”，而是让它生成后“检查”。生成和检查是两个不同的注意力通道，后者对规则的执行度更高。

5.3 风格覆盖的取舍，什么时候“在 Prompt 里忍一忍”

并不是所有风格偏差都值得在 Prompt 层面纠正。有一个决策矩阵可以帮助你判断：

这个矩阵的核心逻辑是：把 Prompt 的注意力预算留给那些影响大、修复成本高、工具无法自动处理的偏差，其他的交给 CR 和自动化工具。 那些在 Prompt 里试图控制每一条 import 格式的行为，本质上是在浪费上下文窗口这个稀缺资源。

六、对话级纠偏：Claude Code 代码生成中的“实时转向”技术

第三级即时纠偏是所有风格控制手段中最灵活、但也是最容易失效的。它的核心问题不是“怎么纠”，而是“什么时候纠、什么样的偏差值得纠”。

6.1 纠偏时机的选择，不是越早越好

很多人一看到 Claude Code 开始输出一段不符合预期的代码，就立刻打断它。这是最差的策略。Claude Code 的代码生成有一个“连贯性窗口”，如果你在它正在生成一个完整逻辑单元时打断，它会丢失当前段落的上下文，导致第二段生成出现更多的风格漂移。

我的原则是：等一个逻辑单元完成后再纠偏。 一个逻辑单元的定义取决于代码类型：

• 普通函数：等整个函数体生成完毕
• 结构体定义：等所有字段和方法生成完毕
• 接口定义：等整个 interface block 闭合

6.2 纠偏的“三明治”表达结构

纠偏 Prompt 的质量直接决定了纠偏效果。一个典型的低质量纠偏：

> 不要用 panic，改成返回 error。

这个指令只能解决当前这一次生成，下一次 Claude Code 还是会用 panic。因为你在纠正一个“症状”，没有纠正“病因”。

更有效的纠偏遵循三明治结构：

正面反馈 → 精确纠偏 → 原因解释

你刚才生成的 user_service.go 的分层结构很清晰，这是好的。
但是错误处理有两处问题：

第 43 行的 panic(err) 违反了我的 CLAUDE.md 中的规则。
请改为 return nil, fmt.Errorf("create user: %w", err)。
第 67 行直接忽略了 tx.Rollback() 的错误返回值，这也需要处理。
为什么强调这个：我们项目的错误会统一在上层 handler 处理并记录到

监控系统。跳过早中层的错误会导致线上问题无法追踪。

三明治结构的精髓在于“原因解释”部分。当 Claude Code 理解了你的动机，它在下一次遇到类似场景时，不再机械地“不用 panic”，而是主动推断出“这个地方应该向上传递 error”。

6.3 一种高级技巧，“纠偏记忆的跨任务携带”

这可能是本文最不为人知的技巧。Claude Code 在一个对话 Session 中积累的纠偏信息，会在 Session 内形成一种“学习效应”。但如果你希望把这次纠偏的成果固化为跨 Session 的规则，你需要做一个动作：

在纠偏被接受后，立即追加一句：

> 请把这次纠偏中涉及到的风格决策，用一句话总结出来，预备写入 CLAUDE.md。

Claude Code 会输出类似：

> 风格决策：所有需要中断流程的异常情况应通过 return error 向上传递，禁止在 middleware/handler 之外的层级使用 panic。

你把这个句子直接追加到 CLAUDE.md 的错误处理章节中。整个过程不超过 30 秒，但它在未来的所有 Session 中都会生效。

我用这个方法在过去 3 个月里持续进化了我们项目的 CLAUDE.md，初始版本只有 87 行，经过 23 次纠偏沉淀后扩展到 131 行，同时规则的必要性（未被后续 PR 质疑过的规则比例）从最初的 71% 提升到了 94%。

七、两个完整案例，从混乱到规范的实战还原

前面讲了框架和技巧，这一章我会还原两个我亲自经手过的真实案例。我会把具体的 Prompt、CLAUDE.md 内容、生成结果以及对比数据全部展示出来。

案例一：一个 Go 微服务的从零构建

背景： 2024 年 12 月，我需要从零搭建一个处理订单支付的 Go 微服务，预计代码量 3000 行左右，涉及 handler、usecase、repository、domain 四个层级。团队共 3 个后端，都使用 Claude Code 辅助开发。

初始做法（翻车阶段）：

我们直接开工，每个人都用自己的风格 Prompt 让 Claude Code 生成代码。第一周结束，我们得到了 2400 行代码，但代码审查时发现问题严重：

• 三个人的 error 处理风格完全不同
• 有一个人用 GORM 的 db.First()，另一个人用 db.Where().First()
• repository 层混入了大量业务逻辑（包括一个藏在 repository 里的优惠券过期判断）
• 日志格式有两种：zerolog 和 logrus 混用（因为一个人的 Prompt 里写了“用 logrus”）

重构方案：

我们用了一下午做了一次“风格对齐 Sprint”，这不是在写业务代码，而是专门用来构建风格基础设施：

1. 写出项目级 CLAUDE.md（142 行，覆盖技术栈、架构、命名、错误处理、数据库操作、日志）
2. 确定任务级 Prompt 模板（约 80 字的风格引用段）
3. 制定纠偏记录规范（三明治结构）

重构后效果：

用同一批开发者在同样的 5 个工作日内，重写整个订单支付服务。结果对比如下：

代码行数下降 11% 是一个意料之外的结果。复盘时发现原因 ， 风格统一后，Claude Code 不再生成重复的辅助函数（例如三个人各自写了一个 parseUserID，风格统一后公用了一个）。风格规则不仅控制了输出格式，间接消除了冗余。

案例二：一个 Python 数据分析项目的风格迁移

案例一的 Go 项目是在项目启动时建立风格系统。案例二则是一个更有挑战性的场景：一个已经运行 4 个月的 Python 数据管道项目，15000+ 行代码，之前没有统一的 CLAUDE.md，团队换人后新成员使用 Claude Code 大规模重构。

核心挑战：

存量代码的风格本身不一致（4 个月里 3 个开发者留下 3 种风格遗产），Claude Code 在读取存量代码时会自动“学习”这些不统一的风格，导致新生成的代码风格高度不确定。

解决方案：

传统做法是花大量时间手动规范存量代码。我们没有这个人力。我用了一个反向策略，“用 CLAUDE.md 声明目标风格，用 .claudeignore 隔离干扰源”。

具体操作：

1. 写一份清晰的目标风格 CLAUDE.md（98 行，只包含我们希望达到的风格标准）
2. 创建一个 .claudeignore 文件，标记那些“风格混乱的存量文件”为忽略，不让 Claude Code 读取它们作为上下文
3. 逐个模块重构时，先从 .claudeignore 中移除该模块，让 Claude Code 读取旧代码理解业务逻辑，然后生成遵循 CLAUDE.md 的新代码替换旧代码

这个策略的精妙之处在于：不要求 Claude Code 理解“旧风格的错误”，而是直接让它在一个干净的风格环境（CLAUDE.md 定义的）中处理业务逻辑，然后用 .claudeignore 控制它看到的旧代码范围。

效果：

迁移过程中新生成的 8400 行代码，风格一致性得分达到 94%，而迁移前新生成代码的得分只有 58%。更重要的是，我们不需要在处理业务逻辑的同时处理历史风格债务，这两个问题被解耦了。

八、跨语言风格控制，一套规则，多语言适用

如果你同时维护 Go、Python、TypeScript 三个项目，是否需要维护三套完全独立的 CLAUDE.md？我的答案是：80% 的架构级规则可以跨语言复用，20% 的语言特定规则需要独立维护。

8.1 可跨语言复用的“元规则”

以下四类规则，写成一份独立的 ARCHITECTURE.md，然后在各语言的 CLAUDE.md 中引用即可：

1. 架构分层约定：clean architecture / DDD 的分层逻辑与语言无关
2. 命名逻辑：“描述性命名优于简写”、“函数名体现动作”等原则
3. 错误处理哲学：“不吞掉错误”、“wrap 后传递”、“集中日志记录”
4. 设计约束：“函数不超过 N 行”、“单一职责”、“依赖注入”

8.2 必须语言特定的“具体规则”

以下规则必须按语言各自定义：

• 具体的命名格式（Go 的 PascalCase vs Python 的 snake_case）
• 具体的工具链（Go 的 zerolog vs Python 的 structlog）
• 具体的语法特性约束（Go 的 interface 用法 vs TypeScript 的 type 用法）

8.3 多语言 CLAUDE.md 管理结构

我目前的目录结构是这样的：

project-root/
├── .claude/

│   ├── ARCHITECTURE.md          # 跨语言元规则

│   ├── go/

│   │   └── CLAUDE.md            # Go 特定规则（引用 ARCHITECTURE.md）

│   ├── python/

│   │   └── CLAUDE.md            # Python 特定规则

│   └── typescript/

│       └── CLAUDE.md            # TypeScript 特定规则

各语言的 CLAUDE.md 开头都有这样一句：

本文件补充说明语言特定的风格约定。
关于项目架构、通用设计原则，参见 ../ARCHITECTURE.md。

这套结构在前文提到的 4 万行 Saas 项目中运行了 5 个月，跨语言风格一致性保持在 85% 以上。如果没有元规则层，跨语言的一致性通常不超过 50%，因为这会让每个语言的 CLAUDE.md 各自演化，最终产生大量不一致的架构级约定。

九、量化评估，你的风格控制效果到底好不好

风格控制不能用“我感觉好多了”来评估。如果无法量化，你无法说服团队投入时间维护 CLAUDE.md，也无法持续优化规则。

这里是我使用的一套三层评估体系：

9.1 L2：自动化检测层

使用静态分析工具扫描 Claude Code 生成的代码，输出违规数。Go 项目用 golangci-lint 的自定义规则集，Python 用 flake8 + pylint，TypeScript 用 ESLint。

关键指标：Lint 违规密度 = 违规数 / 千行代码

我设定的基线是 < 5 违规/千行代码。低于这个值的项目，风格控制算及格。

9.2 L2：人工审查层

Lint 能检测的规则有限。那些需要语义理解的风格问题（例如“这段代码的分层是否正确”、“错误处理是否完整”），需要在 CR 中追踪。

关键指标：CR 风格类评论占比 = 涉及风格问题的 CR 评论数 / CR 总评论数

我团队目前的这个比例在 12-15% 之间。超过 30% 说明 CLAUDE.md 存在系统性问题。

9.3 L3：长期演化层

这个层级关注规则系统本身的健康度，它是否在持续优化，还是在成为僵尸文档。

关键指标：规则活跃度 = 过去 30 天内更新过的 CLAUDE.md 规则数 / 总规则数

我建议这个值保持在 10-20%。过高说明规则系统不稳定，过低说明它已经停止了演化。

三层评估不需要很大的工作量。L1 完全自动化，L2 融入现有 CR 流程（只需增加一个标签“style”），L3 每个月花 5 分钟数一下。花了 30 分钟建立了这套评估体系后，我每次调整 CLAUDE.md 都能看到指标的反馈，这比“感觉好像更好了”要有用得多。

十、风格控制的边界，知道什么“不该控”

最后这一章是我在实践中反复碰撞出来的认知，控制欲和工程效率之间存在一条红线。

10.1 哪些东西不应该通过 CLAUDE.md 控制

以下三种情况，把控制权交给工具和 CR，而不是 CLAUDE.md：

1. 格式化层的问题

缩进、空格、换行位置，这些应该交给 formatter（gofmt、prettier、black）。CLAUDE.md 里写“缩进 4 个空格”纯粹是在浪费上下文窗口，因为 Claude Code 生成代码后你仍然会跑 formatter。

2. 可以通过 Lint 自动检测且修复成本极低的问题

未使用的 import、可以简化的表达式、缺少大括号的 if 语句，这些在 CI 中几秒就能修掉的东西，没必要占据你的风格规则预算。

3. 高度个性化的、无工程价值的偏好

“我不喜欢用 switch”、“我觉得 map 应该叫 dictionary”，这些纯个人偏好的东西，要么在团队达成共识后写入 CLAUDE.md，要么自己默默接受多样性。不要把 CLAUDE.md 变成个人审美的延伸。

10.2 过度控制的真实代价

2024 年 11 月，我犯过一个错误。我把 CLAUDE.md 扩展到了 237 行，涵盖了从命名到注释标点符号的全部细节。结果非常惨：

• Claude Code 在处理复杂任务时，花了大量上下文窗口来“理解规则”，留给业务逻辑的注意力显著下降
• Bug 率上升，不是因为规则有问题，而是因为规则的认知负荷挤压了逻辑生成的质量
• 开发者开始绕过 CLAUDE.md，他们会删除规则后再生成，因为“太麻烦了”

那次翻车之后，我把 CLAUDE.md 从 237 行砍到了 131 行，聚焦在真正影响代码质量和团队协作的规则上。砍掉的那 106 行，大部分是可以通过工具自动处理的格式化规则，以及一些“写得很对但从来没人真正需要”的细碎约束。

规则系统的黄金标准不是“覆盖一切”，而是“管控最少的关键路径”。 如果你发现 CLAUDE.md 里有一条规则在上一个 Sprint 中没有被任何 PR 触发过讨论或争议，那它大概率是一条多余的规则。

10.3 一个实用的收编清单

如果你正在建立或优化你的风格系统，这份清单可以帮助你做出最后的裁减决策：

对于 CLAUDE.md 中的每条规则，问自己三个问题：

1. 这条规则如果被违反，会导致线上 bug 或明显的技术债吗？，如果不是，考虑删除。
2. 这条规则能否被自动化工具（formatter、linter）完全替代？，如果是，直接删除。
3. 这条规则在过去两次 CR 中是否被引用过？，如果没有，它可能不重要。

用这个标准检视你自己的 CLAUDE.md，你会惊讶于有多少规则从未被真正需要过。

结尾：从一次性的 Prompt 到持久的工程系统

回到文章开头那个让我花了 47 分钟重构生成代码的深夜。现在的我再遇到那个场景，不会把时间花在手动修改上，而是花 30 分钟建一套 CLAUDE.md 基础设施，因为我知道那个投入的回报曲线是指数级的。

控制 Claude Code 的代码输出风格，真正的杠杆点不在每一次的 Prompt 撰写上，而在于你是否愿意把风格从“话术”升级为“系统”。 一套好的风格规则体系，它不需要你在每次任务中重复自己，它会让 Claude Code 自主对齐你的团队标准，它可以在开发者之间传递，可以被版本管理追溯，可以随着项目演进而持续进化。

下一件事该做什么很清晰：打开你当前最核心的那个项目，用一个下午的时间完成四步法，让 Claude Code 反推现有风格、你做增删改、小任务压测、提交进 Git。 就这一个下午的投入，你未来的每一个代码生成任务都会在它定义的标准上运行。你不再需要每次写 Prompt 时都回忆一遍团队的命名规范，CLAUDE.md 替你记住了。

这不是一个“更好写 Prompt”的问题，这是一个“把个人手艺沉淀为团队资产”的问题。前者让你今天省 10 分钟，后者让整个团队未来少做几千次手动重构。两者的权重不在同一个数量级。