使用 claude code 为 Kubernetes 编写编排文件的体验

上周四凌晨两点，我盯着监控面板上那个刺眼的 CrashLoopBackOff，指甲几乎掐进掌心。Nginx 的 Deployment 刚上线 30 秒就被 Kubelet 连续杀了 7 次，而这份编排文件，整整 127 行的 YAML，完全出自 Claude Code 之手。我看了一眼它的输出：“看起来没问题了，Deployment 已经就绪。”没问题。是的。它甚至连 readinessProbe 的端口都写错了，把 8080 写成了 80。Nginx 当然没在 80 上暴露健康检查端点。但这不是最要命的。最要命的是，这份文件没有设置任何 resources.limits，而那个节点上还跑着我们的核心支付服务。

这就是我今天想聊的东西：用 Claude Code 写 Kubernetes 编排文件，到底是怎样的体验？

不是“能不能写”的问题。它能写。能写到你惊叹，也能写到你想拔电源。真正的体验，藏在“能写”到“好用”的这一段距离里，这段距离叫作：你对 K8s 的理解深度，决定了 Claude Code 是帮手还是杀手。

我总共用 Claude Code 生成了超过 200 个 Kubernetes 编排文件，覆盖 Deployment、Service、ConfigMap、StatefulSet、Ingress、HPA 六类资源，涉及 4 个不同的生产集群环境和 11 个微服务模块。这篇文章没有任何 AI 代笔，每一个坑、每一行对比代码、每一个“别这么干”的警告，都是我亲手踩出来、亲手修出来的。往下读，我会告诉你这些编排文件在什么样的情况下会炸，为什么会炸，以及怎么让它不炸。

一、核心结论：Claude Code 不是一个 YAML 生成器，它是一个意图翻译器，翻译得好不好，看你的“提示词工程质量”

很多人的第一反应是：“哦，Claude Code 能自动写 K8s YAML 了？那我以后不用手搓了。”这个认知在第一个 Deployment 生成出来的 30 秒内就会崩塌。

我在实际使用中发现，Claude Code 对 Kubernetes 编排文件的处理，本质上经历的是一层“自然语言 → 逻辑结构 → API 对象 → YAML 字段”的转换链路。问题就出在这里：它对 YAML 语法和 K8s API 对象的字段定义非常熟悉，但对你公司的集群拓扑、你的命名约定、你的安全策略、你的容量规划，一无所知。

举个例子。我给它一个提示词：“帮我创建一个部署 Nginx 的 Deployment，用最新稳定版镜像，需要保证高可用。”

它给我的 YAML（精简版）：

apiVersion: apps/v1
kind: Deployment

metadata:

name: nginx-deployment

spec:

replicas: 3

selector:

matchLabels:

app: nginx

template:

metadata:

labels:

app: nginx

spec:

containers:

name: nginx

image: nginx:latest

ports:

containerPort: 80

看起来对吗？对。但这份文件一旦上线，至少会有四个问题等着你：

1. 镜像用 latest 标签：每次 Pod 重启都可能拉取到不同的 Nginx 版本，没法确定当前运行的是哪个版本。更重要的是，imagePullPolicy 默认是 IfNotPresent，你的节点上可能缓存了三个月前的 latest，而另一个节点上拉到了新的，行为不一致，这是生产环境的噩梦。
2. 没有资源限制：resources 字段整个缺失。这意味着这个 Nginx 可以根据内核 CFS 调度器的“意愿”无限消耗 CPU，也可以在内存压力下被 OOM Killer 第一个干掉。你的集群节点越大，这个问题越隐蔽。
3. 没有健康检查：livenessProbe 和 readinessProbe 都没有。Kubelet 只知道容器进程在跑，但不知道 Nginx 是否真的在正常处理请求。如果 Nginx 的配置错误导致 worker 卡死但 master 进程还活着，流量会一直打到这个“半死不活”的 Pod。
4. 没有任何部署策略：默认的 strategy.type 是 RollingUpdate，但 maxSurge 和 maxUnavailable 都没指定。在高峰时段，默认的 25% 不可用意味着可能同时有 1 个 Pod 被干掉，而你的其他副本还没准备好。

核心结论就是：Claude Code 给你的是“能跑”的 YAML，不是“能扛住流量”的 YAML。 这之间隔着一整套生产级实践。接下来的每一节，我都会带你进入一个具体的翻车场景，展示 Claude Code 的“默认行为”和“你应该做的修正”，让你真正理解它在这件事上的能力边界。

二、第一个大坑：资源限制，Claude Code 默认生成的 Deployment，是一个“资源黑洞”

2.1 现象描述：一份“完美”的 Deployment 为什么让节点 CPU 飙到 95%

我在一个 4 核 16G 的测试节点上做过一个对照实验：

• 组 A：使用 Claude Code 生成的默认 Deployment（无 resources）
• 组 B：手动添加了合理 requests/limits 的 Deployment

两组都运行同一个 Golang 微服务，这个服务在启动时会进行一次内存密集型的数据预热，持续约 40 秒。

实验结果（真实数据）：

从数据里看得很清楚：没有资源限制，一个 Pod 就能把整台节点拖下水。但 Claude Code 默认不会给你加 resources 字段。我测试了 30 次不同复杂度的提示词，只要不在提示词里显式提到“资源限制”、“requests”、“limits”这些词，它永远不会主动加这个字段。

2.2 Claude Code 为什么默认不写 resources？

不是因为 Claude Code “不知道”有 resources 这个字段。你问它：“Deployment 可以设置 resources 吗？”它会准确地回答你，甚至能写出正确的语法。问题出在它的“安全策略”：它在生成 Kubernetes 资源时，遵循的是 “最小配置”原则，只输出你明确要求的字段，保留其他字段为空，让 Kubernetes 使用系统默认值。

而 Kubernetes 对“不写 resources”的默认行为是：不设限。 这个组合非常危险。对 Kubernetes 而言，“不设限”意味着这个 Pod 的 QoS 等级是 BestEffort，最低优先级。当节点资源紧张时，它会被第一个杀掉。同时，它也可以无限制地消耗空闲资源，影响同一个节点上的 Burstable 和 Guaranteed 级别的 Pod。

2.3 正确的做法：在提示词里建立“资源限制的强制性规则”

给 Claude Code 写提示词时，我总结出了一条铁律：

永远不要指望 Claude Code 自动帮你加 resources。你必须把它作为提示词里的“刚性约束”写进去。

我推荐的提示词模板：

“为以下服务创建一个 Deployment。强制要求：

1. 必须设置 resources.requests 和 resources.limits
2. requests.cpu 不低于 100m，requests.memory 不低于 128Mi
3. limits.cpu 不超过 1000m，limits.memory 不超过 2Gi
4. 如果服务是 Java 应用，JAVA_OPTS 中的 -Xmx 必须与 limits.memory 匹配（limits 的 70%）
5. 不要在生成结果中遗漏 resources 字段，这是硬性规定”

我测试了 20 次加上这条约束的提示词，resources 字段的生成率从 0% 提升到了 100%。 但还有一个新问题：Claude Code 在没有具体指标参考时，会给出一个“四平八稳”的默认值：cpu: 250m, memory: 256Mi。这个值对大多数服务来说是安全的，但对内存密集型服务（比如 JVM 应用）来说严重偏低。

进阶做法：在提示词中提供你服务的真实资源消耗基线。 我通常会在提示词里贴上我们 Grafana 面板上过去 7 天的资源消耗截图描述，让 Claude Code 根据实际数据来推演合理的 requests 和 limits。这个做法让生成出来的 limits 准确率（以不触发 OOM 和不浪费 CPU 为标准）从大约 40% 提升到了 85% 以上。

三、第二个大坑：健康检查，Claude Code 写出来的探活，大概率不是“真探活”

3.1 liveness 和 readiness 的本质区别，Claude Code 根本不 care

在用 Claude Code 生成 K8s 编排文件的过程中，我发现它对健康检查的理解停留在“有就行”的层面。它会很“贴心”地给你加上这样的探活配置：

livenessProbe:
httpGet:

path: /

port: 80

initialDelaySeconds: 30

periodSeconds: 10

readinessProbe:

httpGet:

path: /

port: 80

initialDelaySeconds: 5

periodSeconds: 5

这种配置在生产环境里，叫做“假装有探活”。

问题在哪？

• 路径 / 不区分服务状态：Nginx 返回 200 OK 只说明 HTTP 服务器在运行，不代表它配置正确、能代理到后端。你的后端全宕了，Nginx 返回一堆 502，但探活路径 / 依然返回 200。结果：Pod 永远不会重启，流量永远打到坏 Pod。
• liveness 和 readiness 连路径都一样：这是最常见的错误。liveness 回答的问题是：“容器还活着吗？需不需要杀掉重建？” readiness 回答的问题是：“容器能接流量了吗？要不要从 Service 的 Endpoints 摘掉？” 两个完全不同的目的，用了完全相同的检查路径。这意味着当服务真的出问题、需要从流量中摘除时，它要么也被 liveness 杀掉重启（雪上加霜），要么 readiness 根本没发现。

3.2 真实案例：一次因探活配置不当导致的“全站雪崩”

2024 年 11 月，我们上线了一个基于 Go 的 API 网关服务。编排文件 80% 由 Claude Code 生成。这是当时的探活配置（由 Claude Code 自动生成）：

livenessProbe:
httpGet:

path: /health

port: 8080

initialDelaySeconds: 15

periodSeconds: 20

timeoutSeconds: 5

failureThreshold: 3

readinessProbe:

httpGet:

path: /health

port: 8080

initialDelaySeconds: 10

periodSeconds: 10

服务上线第二天，后端一个关键数据库发生短暂连接超时（持续约 40 秒）。此时 API 网关的 /health 端点（它仅仅检查进程是否存活）依然返回 200。liveness 没触发，readiness 也没触发，流量继续涌入这个已经无法连接数据库的网关 Pod。 所有经过这个网关的请求都返回 502，而这些 502 又触发了上游重试逻辑，重试又产生新的请求打到另一个网关 Pod，形成流量放大。

最终结果：一个数据库 40 秒的抖动，因为探活配置的失效，演变成了一次持续 4 分钟的全局服务不可用。

3.3 修正方案：用“语义化探活”替代“存在性探活”

在使用 Claude Code 生成编排文件时，我会在提示词中加入明确的探活规范：

“livenessProbe 和 readinessProbe 必须遵循以下规则：

• readinessProbe 必须检查服务是否能够处理业务请求，路径应为 /ready 而非 /health
• /ready 端点必须检查该服务依赖的关键后端（数据库、缓存、消息队列）是否就绪
• livenessProbe 只检查进程是否死锁或不可恢复，路径为 /live，且 failureThreshold 至少为 5
• readinessProbe 的 failureThreshold 设为 2，让它快速摘除不健康的 Pod
• 禁止 liveness 和 readiness 使用同一路径”

另外有一个必须补的知识： 手动检查 Claude Code 生成的所有探活的 initialDelaySeconds。对于 Java 或启动较慢的服务，这个值很容易被 Claude Code 设得过低（它默认倾向 5-15 秒）。如果你的应用启动需要 60 秒，而 initialDelaySeconds 是 10 秒，Kubelet 会在你的应用还没启动完时就开始执行探活检查，反复失败、反复重启。这个循环叫 CrashLoopBackOff 陷阱，Claude Code 是制造这种陷阱的专家。

我把修正后的探活规范套用到一个 Spring Boot 服务上，效果对比：

这个对比说明：Claude Code 给你的只是一个 API 调用的合法格式，它不负责判断这个探活“能不能真的探出问题”。 那个判断，只能你来做。

四、第三个大坑：ConfigMap 与 Secret 的更新，Claude Code 生成了一个“时间胶囊”

4.1 只要你挂载 ConfigMap 当配置文件，Pod 就进入“定格状态”

Claude Code 在帮你写编排文件时，非常喜欢推荐使用 ConfigMap 挂载为卷的方式来管理配置。标准生成逻辑是这样的：

volumes:

name: config

configMap:

name: myapp-config

containers:

name: myapp

volumeMounts:

name: config

mountPath: /etc/myapp/config.yaml

subPath: config.yaml

这个写法本身没问题，问题是：Claude Code 从不告诉你，这种方式挂载的 ConfigMap 更新后，Pod 内的文件不会自动重载，Kubernetes 更不会自动重启你的 Pod。 Kubelet 确实会在 ConfigMap 改变后更新挂载卷中的文件（有一定延迟，通常是 60-90 秒的 kubelet 同步周期），但你的应用读取配置文件通常只在启动时读一次。配置变了，应用不知道，流量还在跑，这就是“运行态配置漂移”。

4.2 我在生产环境踩过的“配置无效”故障

2025 年 1 月，我需要紧急调整一个 Node.js 服务的日志级别，从 info 改为 debug 以排查一个线上的间歇性问题。我用 kubectl edit configmap 改了配置，等了 2 分钟确认挂载卷已经更新，然后让同事去查日志。

什么都没有发生。日志级别还是 info。

原因是：Node.js 应用在启动时用 fs.readFileSync 读取了配置文件，之后就再也没读过。虽然 Kubelet 已经把新的 ConfigMap 内容同步到了 Pod 的挂载路径，但进程根本不知道这件事。Claude Code 生成编排文件时，它只负责把 ConfigMap 挂进去，不负责告诉你这个应用会不会在运行时重新加载配置。

更糟的情况是 StatefulSet 或者 Deployment 使用 subPath 挂载 ConfigMap 的单个文件。 在这种情况下，Kubelet 不会自动更新 挂载卷中的文件。subPath 挂载的文件在 Pod 生命周期内是固定的。你改一百遍 ConfigMap，Pod 里的文件纹丝不动。这是 Kubernetes 的设计行为，但 Claude Code 不会主动告诉你这一点。

4.3 三种修正方案及其适用场景

我在不同服务上测试了三种应对 ConfigMap 更新的方案，以下是针对不同场景的推荐：

方案 1：使用 Reloader Sidecar（最简单、适合 80% 场景）

安装 Stakater Reloader（一个 Kubernetes Controller），它会在 ConfigMap 或 Secret 变更时自动触发关联的 Deployment/DaemonSet/StatefulSet 执行滚动更新。你不需要改代码，只需要在 Deployment 上加一个 annotation：

metadata:
annotations:

reloader.stakater.com/auto: "true"

优点：零代码侵入，Claude Code 生成的编排文件加一行 annotation 就行。

缺点：每次配置变更都会触发 Pod 重建，服务会有短暂中断。

方案 2：应用内实现文件监听（适合对重启敏感的服务）

在应用代码中使用 fs.watch（Node.js）、inotify（Go/Python）或 Spring Cloud Config 等机制监听配置文件变更。这需要修改应用代码，但可以做到配置热更新，无需重启 Pod。

优点：无 Pod 重建，零中断。

缺点：要求应用本身支持，且 Claude Code 无法帮你改这层逻辑。

方案 3：使用 Checksum Annotation（最精准但最麻烦）

在 Deployment 的 spec.template.metadata.annotations 中加入 ConfigMap 的 SHA256 校验和：

spec:
template:

metadata:

annotations:

configmap-checksum: "{{ include (print $.Template.BasePath "/configmap.yaml") . | sha256sum }}"

任何 ConfigMap 变更都会导致 annotation 值变化，触发 Deployment 滚动更新。

优点：精确可控，只在真正变更时触发。

缺点：需要 Helm Chart 或 Kustomize 配合，裸 YAML 无法动态计算校验和。

对于使用 Claude Code 生成编排文件的场景，我推荐默认使用方案 1（Reloader），因为它的部署成本最低，只需要在你的 Helm Chart 或基础 YAML 模板中加入一个 annotation，Claude Code 生成的 99% 的 Deployment 都可以直接套用。但如果你的服务是交易链路的核心服务，上线窗口极其有限，那么必须推动应用团队实现方案 2，把这层能力写进应用的基础框架。

五、第四个陷阱：Service 的 Selector 与流量策略，看似简单，实则暗藏“断流”与“跑偏”

5.1 Claude Code 在 Service 上犯的最高频错误：Selector 泛化

我统计了过去 3 个月中 Claude Code 为我生成的 47 个 Service YAML，发现其中有 12 个（约 25%）存在 Selector 标签过宽或过窄的问题。典型错误案例：

# 错误版本：selector 太宽泛
apiVersion: v1

kind: Service

metadata:

name: user-svc

spec:

selector:

app: user  # 只用一个标签

ports:

port: 80

targetPort: 8080

当你的集群里存在多个环境（如 dev、staging、prod）共用同一命名空间时，这个 Service 会把 dev 和 prod 的 Pod 全选进去。流量会按等概率分发到完全不同版本的代码上，这个 Bug 极端隐蔽，因为看起来“有时候是好的”。

修正方案：在提示词里强制 Claude Code 使用三标签体系：

selector:
app: user

env: production

version: v2.1.0

这是我自己在实践中总结的“标签三要素”原则：应用名 + 环境名 + 版本号。少一个都不行。Claude Code 不会主动替你建立这个规范，它默认的行为是“最少标签匹配”，这恰恰是 Service 配置的大忌。

5.2 externalTrafficPolicy 的隐藏行为

另一个 Claude Code 几乎从不解释的字段，是 Service 的 externalTrafficPolicy。当你使用 NodePort 或 LoadBalancer 类型的 Service 时，Claude Code 可能会建议你设置 externalTrafficPolicy: Local 以保留客户端源 IP。它会生成这样的配置：

apiVersion: v1
kind: Service

metadata:

name: api-gateway

spec:

type: LoadBalancer

externalTrafficPolicy: Local

selector:

app: api-gateway

ports:

port: 443

targetPort: 8443

Claude Code 不会告诉你：当 externalTrafficPolicy: Local 时，只有接收流量的节点上有对应 Pod 时，流量才能被正确转发。如果某个节点上恰巧没有这个 Service 的 Endpoint Pod，流量到了那个节点就直接丢弃。 这在 Pod 分布不均匀时会造成“部分请求黑洞”，请求发到负载均衡器，被转发到节点 A，但节点 A 上没有对应 Pod，返回“connection refused”，而用户明明看到 Service 是 Running 的。

修正建议：

• 如果你的场景可以用 externalTrafficPolicy: Cluster（默认值），就不要改成 Local。源 IP 可以通过其他方式（如 Proxy Protocol、X-Forwarded-For）传递。
• 如果必须使用 Local，请确保配合 Pod 反亲和性（podAntiAffinity） 或 DaemonSet 保证每个节点上都有至少一个 Pod。
• 更优雅的方案：在 LoadBalancer 层使用支持 Proxy Protocol 的负载均衡器（如 AWS NLB、HAProxy），将源 IP 信息通过协议头传入，Service 端保持默认的 Cluster 模式不变。

一句话总结：除非你清楚知道 Local 策略意味着什么且已经处理好了 Pod 分布问题，否则不要碰它。Claude Code 不会替你评估这个风险。

六、第五个陷阱：滚动更新策略，Claude Code 的默认值，让发版变成赌博

6.1 默认 RollingUpdate 参数的“隐蔽暴力”

Claude Code 生成的 Deployment 中，绝大多数不会显式设置 strategy 字段，这意味着 Kubernetes 使用默认值：

strategy:
type: RollingUpdate

rollingUpdate:

maxSurge: 25%

maxUnavailable: 25%

当你只有 3 个副本时：maxUnavailable: 25% 向下取整等于 0（实际上 K8s 会保证至少 1 个不可用），maxSurge: 25% 向上取整等于 1。这个组合的效果是：在滚动更新期间，你的服务副本数会在 2 到 4 之间波动。 如果这 3 个 Pod 的 CPU 使用率本来就接近 limits，少掉 1 个 Pod 意味着另外 2 个 Pod 分摊全部流量，请求延迟翻倍甚至更高。

我在一个流量高峰时执行了一次“小幅配置修改”的 Deployment 更新（只改了一个环境变量），Claude Code 生成的编排文件使用默认策略。更新持续了 7 分钟，期间 P99 延迟从 180ms 飙到 2400ms，直接导致客户端超时重试风暴。

6.2 不同场景下的策略调整建议

根据服务的流量特征和副本数，我把策略分成了三类：

高流量服务（QPS > 1000，副本数 ≥ 10）：

strategy:
type: RollingUpdate

rollingUpdate:

maxSurge: 2          # 绝对数值，非百分比

maxUnavailable: 0    # 一个都不能少

用绝对数值而非百分比，让我可以精确控制同时新增的 Pod 数量。maxUnavailable: 0 保证任何时刻都有至少满配置的副本在服务。

低流量但对可用性要求极高的核心服务：

使用蓝绿发布或金丝雀发布，不依赖 Deployment 原生的 RollingUpdate。这需要在 Service 层做流量切分（如使用 Istio 的 VirtualService 做权重路由），Claude Code 对此支持很差，目前不适合用 AI 生成这部分编排文件。

批处理 / 定时任务 / 后台服务：

strategy:
type: Recreate   # 先全删再新建

Claude Code 几乎从不建议 Recreate，因为它觉得“会让服务中断”。但对于非实时服务，Recreate 可以避免新旧版本同时运行的兼容性问题。在提示词里加上：“如果这不是面向用户的在线服务，使用 strategy.type: Recreate。”

行动建议：永远不要在给 Claude Code 的提示词中省略更新策略。 把它作为每次生成 Deployment 时的必填约束，格式就按上面的分类来。这是我的提示词模板段落：

“此 Deployment 面向在线流量，QPS 约 1500，请设置 RollingUpdate 策略，maxSurge=2，maxUnavailable=0，使用绝对数值而非百分比。”

七、你才是编排文件的“守门员”：一套可供参考的 Claude Code 协作流程

7.1 别把 Claude Code 当成“全自动工厂”，当成“实习生”来管

这个心态转换非常重要。我现在使用 Claude Code 写 K8s 编排文件的标准流程是这样的：

步骤 1：写清楚“硬约束”提示词（约 200-400 字）

• 必须包含：资源限制、探活规范、标签体系、更新策略、镜像策略
• 用否定句式标出禁止行为：“不要使用 latest 标签”、“不要遗漏 resources 字段”

步骤 2：第一轮生成后，人工检查 5 个“杀手级检查点”

1. image 字段是否用了具体版本 tag？（不是 latest）
2. resources.requests 和 resources.limits 是否存在？
3. livenessProbe.path 和 readinessProbe.path 是否不同？
4. Service 的 selector 是否包含环境标签？
5. 更新策略是否根据服务特征显式指定？

这 5 个检查点覆盖了我踩过的 80% 以上的坑。整个过程不超过 3 分钟。

步骤 3：在 staging 环境执行“4 步验证法”

1. kubectl apply –dry-run=server 验证语法
2. kubectl diff -f deployment.yaml 对比与现网差异
3. 灰度部署到 staging，运行 kubectl describe 查看 Events
4. 执行至少 10 分钟的负载测试，监控 P99 延迟和错误率

步骤 4：生产发布，灰度先行，全量在后

• 如果是新服务：先在 production 部署 1 个副本，观察 30 分钟
• 如果是已有服务更新：使用金丝雀发布工具（如 Argo Rollouts），不要直接用 kubectl apply

7.2 建立一个“团队级 K8s 编排文件规范文档”，喂给 Claude Code

Claude Code 最强大的能力之一是可以在项目级别配置持久化的指令。在你的项目根目录创建一个 .claude/rules.md（或通过 Claude Code 的项目配置功能），把团队的 K8s 规范写进去。

我团队现在的 rules 文件片段：

# Kubernetes 编排文件生成规范
强制性字段（任何 Deployment 都必须包含）

image 必须使用完整 tag，禁止 latest

resources.requests 和 limits 必须设置

liveness 和 readiness 路径必须不同

selector 必须同时包含 app、env、version 三个标签

默认值

imagePullPolicy: IfNotPresent（有 tag 时） / Always（使用特定分支构建时）

terminationGracePeriodSeconds: 30

资源基线

微服务默认 requests: cpu=100m, memory=128Mi

微服务默认 limits: cpu=500m, memory=512Mi

JVM 应用的 memory limits 应为 requests 的 2 倍

有了这份规范文档，Claude Code 生成的编排文件准确率从最初的大约 40%（需要较多修改才能上生产）提升到了约 85%（只需轻微调整即可上线）。 这个提升不是 Claude Code 变聪明了，而是你给了它足够清晰的“上下文”和“预期”。

7.3 什么场景下，我已经完全不用 Claude Code 写编排文件了

坦率地说，并不是所有场景都适合用 Claude Code。在以下情况中，我经过多次尝试后放弃了 AI 辅助，回到了纯手写模式：

• 涉及 CRD 的复杂编排：如 Istio VirtualService/DestinationRule、CertManager Certificate。Claude Code 对这些第三方 CRD 的知识存在滞后，字段理解常有偏差。
• 涉及多级继承的 Helm Chart：Helm 的模板语法 + values 继承 + 条件渲染的组合，Claude Code 目前处理得不好，容易出现模板语法错误或遗漏条件分支。
• 安全敏感配置：如 RBAC 的 RoleBinding、NetworkPolicy 的 egress 规则、PodSecurityPolicy。这些配置一个标点符号的错误都可能导致权限漏洞，目前不适合交给 AI 做第一次生成。
• 极致性能优化的场景：需要精确控制 CPU Manager 策略、拓扑感知调度（Topology Spread Constraints）、HugePages 等高级特性时，Claude Code 缺乏足够的上下文来判断你的节点拓扑和硬件布局。

我现在的原则是：80% 的标准 Deployment/Service/ConfigMap 用 Claude Code 生成初稿 + 人工修正；20% 的复杂场景纯手写。 这个比例在过去半年里从 30/70 变成了 80/20，Claude Code 确实在不断进步，但“最后的 20%”才是真正考验人的地方。

八、效率数据：用了半年 Claude Code 写编排文件，到底省了多少时间？

8.1 统计口径说明

以下数据基于我个人的 Git 提交记录和 Toggl 时间追踪，统计周期为 2024 年 10 月至 2025 年 3 月（6 个月），共涉及 214 个 Kubernetes 编排文件的创建或重大修改。

我把文件分为三类：

• A 类：全新 Deployment/Service/ConfigMap 创建
• B 类：已有文件的重大修改（30% 以上字段变更）
• C 类：已有文件的小幅修改（环境变量、资源微调等）

8.2 实际效率数据

一个有意思的发现：C 类小幅修改中，直接用 kubectl edit 比用 Claude Code 快 25%。 Claude Code 的优势在从零到一的创建场景，而不是已有文件的微调。这个发现让我调整了使用策略：小于 10 行的改动，直接手改；超过 30 行或涉及新增资源块的改动，才启动 Claude Code。

8.3 质量对比：Claude Code 生成的编排文件引入的 Bug 率

我从团队的 Postmortem 和变更记录中提取了过去 6 个月中由编排文件错误导致的生产事件。在总共 11 起事件中：

数据表明：Claude Code 生成后不经人工检查直接上线，Bug 率比手写还高。 但经过标准检查流程后，Bug 率降到了远低于手写的水平。这不是 Claude Code 的错，它的定位一直是为有经验的人提效，而不是替代有经验的人。

最令我意外的是趋势线。 随着我不断优化提示词模板和项目 rules 文件，Claude Code 输出的“直接可用率”从 35% 提升到了 68%，同时我花在修改上的时间从 18 分钟降到了 5 分钟。这让我相信：Claude Code 的 K8s 编排文件生成能力，上限不取决于模型本身，而是取决于你给它构建的“知识上下文”有多丰富。

九、从体验到建议：如果你现在就开始用 Claude Code 写编排文件，这 7 条原则请记下来

基于过去 6 个月 200+ 个文件的实战经验，我把所有踩过的坑、踩过坑之后的修正、以及修正后的最佳实践，浓缩成了以下 7 条原则：

原则 1：提示词的“硬约束”永远比“软建议”有效

不要说“请设置合理的资源限制”，要说“必须设置 resources.requests 且 cpu 不低于 100m”。Claude Code 倾向于遵循强指令，弱指令会被它忽略。

原则 2：永远手动检查 5 个“杀手级检查点”

镜像 tag、resources、探活路径、Service selector、更新策略，这五项是我在 200 多次生成中发现的最常见遗漏，逐一检查只要 3 分钟，但漏掉任何一个都可能在凌晨让你爬起来。

原则 3：建立团队级 rules 文件，让 Claude Code 学会你的“规矩”

项目根目录下的 .claude/rules.md 是所有对话的“隐形约束”。把所有“我们团队的原则”写进去，标签规范、镜像仓库、资源基线、探活标准。这比你每次提示词里重复强调高效十倍。

原则 4：探活路径必须区分 liveness 和 readiness，且 readiness 要检查后端依赖

Claude Code 不会帮你区分两者的语义。你必须告诉它：/live 只检查进程，/ready 要检查数据库、缓存、MQ 等所有关键依赖。这是防止故障扩散的第一道防线。

原则 5：ConfigMap 挂载后，应用不会自动重载配置，你需要主动处理

要么装 Reloader，要么让应用支持文件监听。Claude Code 给你的挂载配置只是第一步，下一步的“热更新”问题必须由你来解决。

原则 6：小于 10 行的改动，直接用 kubectl edit，别叫 Claude Code

在 C 类小幅修改上，Claude Code 的交互成本反而更高。知道什么时候不用它，和知道什么时候用它一样重要。

原则 7：永远把 Claude Code 当成“实习生”，不是“大神”

它产出的任何编排文件，默认是“草稿”状态。人工 Review 是你们的最后一道防线。把 CI/CD 管道里加上 kubectl diff 和 kube-score 或 kubeval 的自动校验，把 AI 的产出和人工的判断结成最后一道锁。

结尾：从“能写”到“敢用”之间，隔着你对 Kubernetes 的全部理解

回到开头那个凌晨两点的 CrashLoopBackOff。我曾一度想放弃用 Claude Code 写任何编排文件，因为它给的那份 Deployment 让我在半夜崩溃了整整一个小时。但冷静下来之后，我意识到：错的不是它给了我一份有问题的 YAML，错的是我以为它会给我一份没问题的 YAML。

这个认知转变，是我过去半年在 K8s 编排文件这件事上学到的最重要的一课。

Claude Code 能做的，是在你清晰描述了需求之后，在一秒之内完成你 30 分钟才能写完的字段拼装。但判断那些字段是否合理、是否能扛住生产流量的，只能是你对 Kubernetes 调度器行为的理解、对资源隔离机制的直觉、对探活语义的精确把握、对网络策略的路径推演，这些能力，没有任何一个 AI 能替你补上。

但它能让已经拥有这些能力的你，变成一个效率翻倍的工程师。前提是：你把它当成一把趁手的工具，而不是一个甩手掌柜。

下一步怎么走？如果你的团队现在开始用 Claude Code 写 K8s 编排文件，我建议的行动顺序是：

1. 花一个下午，把团队现有的 K8s 规范沉淀成一份 rules 文件，放进项目根目录
2. 选一个非核心服务作为试点，用本文的“硬约束提示词模板 + 5 检查点 + 4 步验证法”完整跑一遍
3. 用 2-3 周时间积累 20-30 个文件的生成经验，建立自己对 Claude Code 在 K8s 场景下能力边界的直观感受
4. 把经过验证的流程固化成团队 SOP，连同 rules 文件一起作为新人的“AI 协作入职指南”

如果你也在用 Claude Code 写 K8s 编排文件，遇到过它生成了什么让你哭笑不得的 YAML，或者发现了什么我还没提到的坑，请在评论区告诉我。我会把大家的问题整理成一篇“K8s 编排文件避坑合集”，这个合集里应该会有一节叫“那些年，Claude Code 帮我们写的 Bug”。我猜内容会很精彩。