# Im going back to writing code by hand # 我要回归手写代码了 *10 May, 2026* *2026 年 5 月 10 日* This dev-log is getting a lot of attention on HN (scary!): [HN Thread](https://news.ycombinator.com/item?id=48090029). > 这篇开发日志在 HN（Hacker News）上引起了广泛关注（让人有些惶恐！）：[HN 讨论帖](https://news.ycombinator.com/item?id=48090029)。 To those who are coming here from HN: This started as an investigation or rather a question: "How far I can get with building a piece of software by keeping myself completely out of the loop". > 对从 HN 过来的人说一句：这最初是一次探索，或者说是一个疑问：“如果完全将我自己置身事外，我能用 AI 把软件构建到什么程度”。 The tl;dr of this dev log is that I still need to be in the loop to make anything meaningful. Take aways: > 这篇开发日志的太长不看版（TL;DR）是：我仍然需要亲自参与其中，才能做出有意义的东西。主要收获如下： * like "em-dash" is to ai writing, "god-object" is to ai coding > 就像破折号（em-dash）是 AI 写作的典型特征一样，“上帝对象（god-object，指无所不包的庞大代码结构）”也是 AI 编程的典型产物。 * vibe-coding makes everything feel cheap and you may end up losing focus and building bloat > “氛围编程（vibe-coding，指仅靠自然语言提示词让 AI 写代码）”让增加功能感觉非常廉价，你可能会因此失去焦点，最终堆砌出臃肿的代码。 * let a human (you) write the architecture and don't just keep asking it for features > 让人类（你）来编写架构，不要只是不断地向 AI 索要新功能。 * And some AGENTS.md/CLAUDE.md directives that I felt help me stay out of the loop a little more > 还有一些我觉得能帮我尽量少去亲自写代码的 AGENTS.md / CLAUDE.md 指令提示词。 Humans intervention is still needed as of 10/05/2026. You can totally go back now! [3] > 截至 2026 年 5 月 10 日，仍然需要人类的干预。你现在完全可以点返回键离开了！[3] ---

I

Here is k10s:[https://github.com/shvbsle/k10s/tree/archive/go-v0.4.0](https://github.com/shvbsle/k10s/tree/archive/go-v0.4.0) > 这是 k10s 项目：[https://github.com/shvbsle/k10s/tree/archive/go-v0.4.0](https://github.com/shvbsle/k10s/tree/archive/go-v0.4.0) 234 commits. ~30 weekends. Built entirely on vibe-coded sessions with Claude, whenever my tokens lasted long enough to ship something. > 234 次提交。大约 30 个周末。完全依靠与 Claude 的“氛围编程”会话构建而成——只要我的 Token 额度还够支撑交付点东西出来。 I'm archiving my TUI tool and rewriting it from scratch. > 我正准备归档这个 TUI（终端用户界面）工具，并从头开始重写它。 k10s started as a GPU-aware Kubernetes dashboard (and my first foray into building something serious with AI). Think k9s but built for the people running NVIDIA clusters, people who actually care about GPU utilization, DCGM metrics, and which nodes are sitting idle burning $32/hr. I built it in Go with Bubble Tea [1] and it worked. > k10s 最初是一个能感知 GPU 的 Kubernetes 仪表盘（这也是我第一次尝试用 AI 构建严肃的项目）。可以把它想象成专为管理 NVIDIA 集群的人设计的 k9s，适合那些真正在意 GPU 利用率、DCGM 指标以及哪些节点正闲置着每小时烧掉 32 美元的人。我用 Go 语言和 Bubble Tea [1] 框架构建了它，而且它确实能用。 For a while... :( > 至少在一段时间内能用…… :( I learned over these 7 months is worth more than the 1690 lines of `model.go` I'm throwing away. And I think anyone doing serious vibe-coding can benefit from this, because this part doesn't surface much (I feel it gets buried under the demo reels and the velocity wins). > 在这 7 个月里学到的东西，比我即将丢弃的那 1690 行 `model.go` 更有价值。我认为任何在认真尝试“氛围编程”的人都能从中受益，因为这一部分的经验往往不怎么显露出来（我觉得它被掩盖在各种演示视频和开发速度带来的快感之下了）。 tl;dr: AI writes features, not architecture. The longer you let it drive without constraints, the worse the wreckage gets. The velocity makes you think you're winning right up until the moment everything collapses simultaneously. > 太长不看版（TL;DR）：AI 只管写功能，不管写架构。你让它在没有约束的情况下“驾驶”得越久，最终的烂摊子就越严重。极快的开发速度会让你觉得自己赢麻了，直到一切瞬间坍塌的那一刻。

II

### vibe coding high ### 氛围编程的巅峰体验 I started k10s in late September 2025. The first few weeks were magic. I'd prompt Claude with "add a pods view with live updates" and boom, it worked. Resource list views, namespace filtering, log streaming, describe panels, keyboard navigation. Each feature landed clean because the project was small enough that the AI could hold the whole thing in context. > 我在 2025 年 9 月下旬启动了 k10s 项目。最初的几个星期简直就像魔法一样。我提示 Claude “添加一个带有实时更新的 Pods 视图”，轰的一下，它就跑起来了。资源的列表视图、命名空间过滤、日志流、Describe 面板、键盘导航。每一个功能都干净利落地落地了，因为当时的体积还足够小，AI 能够把整个项目保持在上下文记忆中。 The basic k9s clone took maybe 3 weekends. Resource views for pods, nodes, deployments, services. A command palette. Watch-based live updates. Vim keybindings. All working, all vibe-coded in single sessions. I was building at maybe 10x my normal speed and it felt incredible. > 实现一个基础的 k9s 克隆版大概花了 3 个周末。包含了 Pod、Node、Deployment、Service 的资源视图。一个命令面板。基于 Watch 机制的实时更新。Vim 快捷键绑定。全部都能运行，全部是在一个个的单次会话中“氛围编程”写出来的。我的开发速度大概是平时的 10 倍，感觉不可思议。 Then I wanted the main selling point. > 然后我想要实现核心卖点了。 The whole reason k10s exists is the GPU fleet view. A dedicated screen that shows you every node's GPU allocation, utilization from DCGM, temperature, power draw, memory. Not buried in `kubectl describe node` output, but right there in a purpose-built table with color-coded status. Idle nodes in yellow. Busy in green. Saturated in red. > k10s 存在的全部意义就在于 GPU 集群视图（fleet view）。这是一个专门的屏幕，向你展示每个节点的 GPU 分配情况、来自 DCGM 的利用率、温度、功耗和内存。这些信息不再埋藏在 `kubectl describe node` 的输出里，而是就在一个带有状态颜色编码的专用表格里。空闲节点显示黄色。繁忙显示绿色。饱和显示红色。

The fleet view on mock GPU nodes
（在模拟 GPU 节点上的集群视图）

And Claude one-shot it. I prompted for the fleet view, it generated the `FleetView` struct, the tab filtering (GPU/CPU/All), the custom rendering with allocation bars. It looked beautiful. I was riding the high. > Claude 一次性（one-shot）就搞定了。我给出了集群视图的需求，它生成了 `FleetView` 结构体、标签页过滤（GPU/CPU/全部）、带有分配进度条的自定义渲染。看起来美极了。当时我正处于兴奋的巅峰。 Then I typed `:rs pods` to switch back to the pods view. > 然后我输入了 `:rs pods` 准备切换回 Pods 视图。 Nothing rendered. The table was empty. Live updates had stopped. I switched to nodes, it showed stale data from the fleet view's filter. I went back to fleet, the tab counts were wrong. > 什么也没有渲染出来。表格是空的。实时更新也停止了。我切换到 Nodes 视图，它显示的居然是集群视图过滤器遗留下来的陈旧数据。我又切回集群视图，标签页上的计数全错了。 The god object had consumed itself. > 这个“上帝对象”把自己给吞噬了。 This is the title of the blog post. This is where I intervened for the first time. For 7 months I'd been prompting and shipping without ever sitting down and actually reading the code Claude wrote. I'd look at the diff, verify it compiled, test the happy path, move on. But now something was fundamentally broken and I couldn't just prompt my way out of it. > 这就是这篇博客标题的由来。这是我第一次介入代码之中。7 个月来，我一直在写提示词并交付，从来没有坐下来真正阅读过 Claude 写的代码。我只会看看代码比对（Diff），确认它能编译通过，测试一下主流程（happy path），然后继续。但现在，一些根本性的东西坏了，我无法再仅仅通过“写一段提示”来摆脱困境了。 So I sat down and read `model.go`. All 1690 lines. I was horrified. > 所以我坐下来仔细阅读了 `model.go`。整整 1690 行代码。我惊呆了。 Here's what it looked like. One struct to rule them all: > 它看起来是这样的。一个统治一切的结构体： ```go type Model struct { // 3rd party UI components table table.Model paginator paginator.Model commandInput textinput.Model help help.Model // cluster info and state k8sClient *k8s.Client currentGVR schema.GroupVersionResource resourceWatcher watch.Interface resources[]k8s.OrderedResourceFields listOptions metav1.ListOptions clusterInfo *k8s.ClusterInfo logLines[]k8s.LogLine describeContent string currentNamespace string navigationHistory *NavigationHistory logView *LogViewState describeView *DescribeViewState viewMode ViewMode viewWidth int viewHeight int err error pluginRegistry *plugins.Registry helpModal *HelpModal describeViewport *DescribeViewport logViewport *LogViewport logStreamCancel func() logLinesChan <-chan k8s.LogLine horizontalOffset int mouse *MouseHandler fleetView *FleetView creationTimes []time.Time allResources[]k8s.OrderedResourceFields // fleet's unfiltered set allCreationTimes[]time.Time // fleet's timestamps rawObjects[]unstructured.Unstructured ageColumnIndex int // ... } ``` UI widgets. K8s client. Per-view state for logs, describe, fleet. Navigation history. Caching. Mouse handling. All in one struct. And the `Update()` method was a 500-line function dispatching on `msg.(type)` with 110 switch/case branches. > UI 组件。K8s 客户端。日志、Describe、集群等按视图划分的状态。导航历史。缓存。鼠标事件处理。全都被塞在了一个结构体里。而且 `Update()` 方法是一个 500 行的庞大函数，对 `msg.(type)` 进行分发处理，里面足足包含了 110 个 switch/case 分支。 This is the moment I stopped vibe-coding and started thinking. > 就在这一刻，我停止了氛围编程，开始认真思考。

Ok I guess I'll let you copy logs with your mouse. What could go wrong?
（好吧，我想我会让你用鼠标复制日志。这能出什么岔子呢？）

III

### five tenets from the wreckage ### 从废墟中总结出的五大准则 Here's what I extracted from 7 months of watching AI generate a codebase that slowly ate itself. Each of these is something I did wrong, why it happens with AI-assisted coding, and what you should actually put in your `CLAUDE.md` or `agents.md` to prevent it. > 以下是我看着 AI 在 7 个月里生成一个慢慢自我吞噬的代码库后，所提取出的经验。每一条都代表了我做错的地方、为什么它会在 AI 辅助编程时发生，以及你到底应该在你的 `CLAUDE.md` 或 `agents.md` 中写些什么来防止这种事。 --- **Tenet 1: AI builds features, not architecture.** > **准则 1：AI 编写功能，而不是架构。** Every time I prompted Claude for a feature, it delivered. Perfectly. The fleet view worked on the first try. Log streaming worked. Mouse support worked. The problem is that each feature was implemented in the context of "make this work right now" without any awareness of the 49 other features sharing the same state. > 每次我向 Claude 提出新功能的需求，它都能完美交付。集群视图一次成功。日志流成功。鼠标支持成功。问题在于，每个功能的实现都完全处于“现在马上让这个功能跑起来”的短视视角中，完全没有意识到还有 49 个其他功能在共享同一个状态空间。 Here's what the `resourcesLoadedMsg` handler looks like. This is the code that runs every time you switch views: > 这是 `resourcesLoadedMsg` 处理程序的样子。这是每次你切换视图时都会运行的代码： ```go case resourcesLoadedMsg: m.logLines = nil // Clear log lines when loading resources m.horizontalOffset = 0 // Reset horizontal scroll on resource change if m.currentGVR != msg.gvr && m.resourceWatcher != nil { m.resourceWatcher.Stop() m.resourceWatcher = nil } m.currentGVR = msg.gvr m.currentNamespace = msg.namespace m.listOptions = msg.listOptions m.rawObjects = msg.rawObjects // For nodes: store the full unfiltered set, classify, then filter if msg.gvr.Resource == k8s.ResourceNodes && m.fleetView != nil { m.allResources = msg.resources m.allCreationTimes = msg.creationTimes if len(msg.rawObjects) > 0 { m.fleetView.ClassifyAndCount(m.rawObjectPtrs()) } m.applyFleetFilter() } else { m.resources = msg.resources m.creationTimes = msg.creationTimes m.allResources = nil m.allCreationTimes = nil } ``` See the `if msg.gvr.Resource == k8s.ResourceNodes && m.fleetView != nil` conditional? That's the fleet view being special-cased inside the generic resource loading path. Every new view that needed custom behavior got another branch here. And every branch needed to manually clear the right combination of fields or the previous view's data would bleed through. > 看到 `if msg.gvr.Resource == k8s.ResourceNodes && m.fleetView != nil` 这个条件判断了吗？这就是在通用的资源加载路径中，为集群视图生硬添加的“特例（special-casing）”。每一个需要自定义行为的新视图，都在这里增加了一个额外的分支。而且每个分支都需要手动清除正确的字段组合，否则上一个视图的数据就会渗透（bleed through）过来。 How many `= nil` cleanup lines exist in this file? I counted: > 这个文件里有多少行 `= nil` 清理代码？我数了一下： ```go m.logLines = nil // Clear log lines when loading resources m.allResources = nil // Clear fleet data when not on nodes m.resources = nil // Clear resources when loading logs m.resources = nil // Clear resources when loading describe view m.logLines = nil // Clear log lines when loading describe view m.resources = nil // Clear resources when loading yaml view m.logLines = nil // Clear log lines when loading yaml view m.logLines = nil // ... two more in other handlers m.logLines = nil ``` Nine manual nil assignments scattered across a 1690-line file. Miss one and you get ghost data from the previous view. This is what happens when there's no view isolation. AI can't see this pattern decaying over time because each prompt only touches one code path. > 整整 9 个手动 nil 赋值散布在一个 1690 行的文件里。漏掉一个，你就会得到上一个视图的幽灵数据。这就是没有视图隔离的后果。AI 看不到这种随着时间推移而腐坏的模式，因为每一次对话提示都只触及当前的一条代码路径。 **What to do instead:** Write the architecture yourself before any code. Not a vague design doc. A concrete set of interfaces, message types, and ownership rules. Then put those rules in your `CLAUDE.md` so the AI sees them on every prompt: > **正确的做法：**在写任何代码之前，亲自编写架构。这不是一份模糊的设计文档。而是一组具体的接口、消息类型和所有权规则。然后把这些规则放在你的 `CLAUDE.md` 中，这样 AI 每次处理你的提示词时都能看到它们： ```markdown # Architecture Invariants (CLAUDE.md) # 架构不变准则 - Each view implements the View trait. Views do NOT access other views' state. （每个视图实现 View 接口。视图绝对不访问其他视图的状态。） - All async data arrives via AppMsg variants. No direct field mutation from background tasks. （所有异步数据通过 AppMsg 变体到达。禁止后台任务直接修改字段。） - Adding a new view MUST NOT require modifying existing views. （添加新视图绝不能要求修改现有视图。） - The App struct is a thin router. It owns navigation and message dispatch. Nothing else. （App 结构体是一个薄路由。它只拥有导航和消息分发的职责，没有其他任何职责。） ``` The AI will follow these if you write them down. It just won't invent them for you. > 只要你写下来，AI 就会遵守。它只是不会主动为你发明这些规则。 --- **Tenet 2: The god object is the default AI artifact.** > **准则 2：“上帝对象”是 AI 的默认产物。** AI gravitates toward single-struct-holds-everything because it satisfies the immediate prompt with minimal ceremony. But it gets worse. Because there's no view isolation, key handling becomes a nightmare. Here's the actual key dispatch for the `s` key: > AI 倾向于“把所有东西塞进一个结构体里”，因为这能以最少的繁文缛节满足当下的提示词要求。但这让情况变得更糟。由于没有视图隔离，按键事件处理变成了一场噩梦。这是 `s` 键实际的按键分发代码： ```go case m.config.KeyBind.For(config.ActionToggleAutoScroll, key): if m.currentGVR.Resource == k8s.ResourceLogs { m.logView.Autoscroll = !m.logView.Autoscroll if m.logView.Autoscroll { m.table.GotoBottom() } return m, nil } // Shell exec for pods and containers views if m.currentGVR.Resource == k8s.ResourcePods { // ... 20 lines to look up selected pod, get name, namespace ... return m, m.commandWithPreflights( m.execIntoPod(selectedName, selectedNamespace), m.requireConnection, ) } if m.currentGVR.Resource == k8s.ResourceContainers { // ... container exec logic ... return m, m.commandWithPreflights(m.execIntoContainer(), m.requireConnection) } return m, nil ``` One keybinding. Three completely different behaviors depending on which view you're in. The `s` key means "autoscroll" in logs, "shell" in pods, and "shell into container" in containers. This is all in one flat `switch` because there are no per-view key maps. The AI generated this because I said "add shell support for pods" and it found the nearest key handler and jammed it in. > 一个快捷键。根据你所在的视图，有三种完全不同的行为。`s` 键在日志视图中表示“自动滚动（autoscroll）”，在 Pods 视图中表示“终端（shell）”，在 Containers 视图中表示“进入容器的终端”。这一切都在一个扁平的 `switch` 代码块里，因为没有按视图划分的独立按键映射字典。AI 生成了这段代码，因为我说“为 Pods 添加 shell 支持”，它就找到了最近的按键处理程序并强行塞了进去。 And look at how `Enter` works. This is the drill-down handler: > 再看看 `Enter` 键是如何工作的。这是向下钻取（drill-down）的处理程序： ```go case m.config.KeyBind.For(config.ActionSubmit, key): // Special handling for contexts view if m.currentGVR.Resource == "contexts" { // ... 12 lines ... return m, m.executeCtxCommand([]string{contextName}) } // Special handling for namespaces view if m.currentGVR.Resource == "namespaces" { // ... 12 lines ... return m, m.executeNsCommand([]string{namespaceName}) } if m.currentGVR.Resource == k8s.ResourceLogs { return m, nil } // ... 25 more lines of generic drill-down ... ``` Every view is a conditional in a flat dispatch. There are 20+ occurrences of `m.currentGVR.Resource ==` used as a type discriminator in this single file. Not types. String comparisons. Every new view means touching every handler. > 每一个视图都是这个扁平分发逻辑里的一个 `if` 条件语句。在这个单独的文件里，`m.currentGVR.Resource ==` 作为类型的判别器出现了 20 多次。注意，它靠的不是类型系统，而是字符串比较。每一个新视图都意味着你要去修改所有的处理程序。 **What to do instead:** Put this in your `CLAUDE.md`: > **正确的做法：** 把下面这段放进你的 `CLAUDE.md` 中： ```markdown # State Ownership Rules # 状态所有权规则 - NEVER add fields to the App/Model struct for view-specific state. （绝对不要在 App/Model 结构体中为特定视图的状态添加字段。） - Each view is a separate struct implementing the View trait/interface. （每个视图是一个实现了 View trait/接口的独立结构体。） - Each view declares its own key bindings. The app dispatches keys to the active view. （每个视图声明其自身的快捷键绑定。App 负责将按键分发给当前激活的视图。） - If you need to add a keybinding, add it to the relevant view's keymap, not a global one. （如果你需要添加快捷键，将其添加到相关视图的按键映射中，而不是全局映射。） - Adding a view means adding a file. If your change requires modifying existing views, stop and ask. （添加一个视图意味着添加一个文件。如果你的更改需要修改现有视图，停下来并询问。） ``` The AI will always take the shortest path ("add another if-branch"). Your job is to make the shortest path also the correct path by putting guardrails in the file it reads on every invocation. > AI 总是会选择最短的路径（也就是“再加一个 if 分支”）。你的工作是通过在它每次被唤醒时都会读取的文件中设置护栏，让“最短的路径”同时也是“正确的路径”。 --- **Tenet 3: Velocity illusion widens your scope.** > **准则 3：速度的错觉会拓宽你的边界（范围蔓延）。** This one's psychological, not technical, and I think it's the most dangerous. > 这一条是心理层面的问题而非技术层面的，我认为这是最危险的一条。 When I started k10s, I wanted a GPU-focused tool. For people running training clusters. A niche audience that I'm part of. But vibe-coding made everything feel cheap. "Oh I can add pods view in one session? Let me add deployments too. And services. And a full command palette. And mouse support. And contexts. And namespaces." > 当我开始 k10s 项目时，我想要的是一个专注于 GPU 的工具。为那些运行训练集群的人服务。这是一个我自己也身在其中的小众群体。但“氛围编程”让一切特性的添加都感觉过于廉价了。“哦，我可以在一次会话中加上 Pods 视图？那让我把 Deployments 也加上。还有 Services。再来个完整的命令面板。还有鼠标支持。以及 Contexts。还有 Namespaces。”

damn I added everything in it dawg...
（该死，哥们儿，我把什么都加进去了……）

Suddenly I was building k9s. A general-purpose Kubernetes TUI. For everyone. Because the AI made it feel like each feature was free. > 突然之间，我正在构建 k9s ——一个通用的 Kubernetes TUI 工具。为所有人服务。因为 AI 让我觉得似乎每一个功能都是免费白嫖来的。 It wasn't free. Each feature was another branch in the god object. Here's the keybinding struct: > 这并不是免费的。每一个功能都是上帝对象里的另一个沉重的分支。这是按键绑定的结构体： ```go type keyMap struct { Up, Down, Left, Right key.Binding GotoTop, GotoBottom key.Binding AllNS, DefaultNS key.Binding Enter, Back key.Binding Command, Quit key.Binding Fullscreen key.Binding // log view Autoscroll key.Binding // log view (also shell in pods!) ToggleTime key.Binding // log view WrapText key.Binding // log + describe view CopyLogs key.Binding // log view ToggleLineNums key.Binding // describe view Describe key.Binding // resource views YamlView key.Binding // resource views Edit key.Binding // resource views Shell key.Binding // pods (CONFLICTS with Autoscroll!) FilterLogs key.Binding // log view FleetTabNext key.Binding // fleet view only FleetTabPrev key.Binding // fleet view only } ``` One flat keymap for all views. Comments in parens show which view each binding applies to. `Autoscroll` and `Shell` are both `s`. This "works" because the dispatch checks `m.currentGVR.Resource` before acting. But it means you can't reason about keybindings locally. You have to trace through the entire 500-line Update function to know what a key does. > 所有视图共用一个扁平的按键映射。圆括号里的注释标明了每个绑定适用于哪个视图。`Autoscroll` 和 `Shell` 绑定的都是 `s` 键。这“之所以能运行”，是因为事件分发逻辑在执行前检查了 `m.currentGVR.Resource`。但这同时也意味着你无法在局部作用域内推断按键绑定的逻辑。你必须追踪整个 500 行的 Update 函数，才能知道按下一个键到底会发生什么。 The complexity was accumulating invisibly while the velocity metric said "you're shipping!" > 当速度指标在向你欢呼“你在不断交付！”时，复杂性正在不知不觉中悄然累积。 **What to do instead:** Write a vision doc that explicitly says who you're NOT building for, and put the scope boundary in your `CLAUDE.md`: > **正确的做法：** 撰写一份愿景文档，明确写明你不为哪些人构建，并把范围（Scope）边界放在你的 `CLAUDE.md` 中： ```markdown # Scope (do NOT expand beyond this) # 范围（不要在此范围之外进行扩展） k10s is for GPU cluster operators. Not all Kubernetes users. （k10s 是为 GPU 集群运维人员准备的。不是所有的 Kubernetes 用户。） Supported views: fleet, node-detail, gpu-detail, workload. That's it. （支持的视图仅有：fleet, node-detail, gpu-detail, workload。仅此而已。） Do NOT add generic resource views (pods, deployments, services). （不要添加通用的资源视图如 pods, deployments, services。） Do NOT add features that duplicate k9s functionality. （不要添加重复 k9s 现存功能的特性。） If a feature request doesn't serve someone running GPU training jobs, reject it. （如果某个功能请求不服务于运行 GPU 训练任务的人员，拒绝它。） ``` Vibe-coding makes you feel like you have infinite implementation budget. You don't. You have infinite LINE budget (the AI will generate as much code as you want). But you have the same finite complexity budget as always. The architecture can only support so many features before it buckles, regardless of how fast you wrote them. The `CLAUDE.md` scope section is you saying no in advance, before the velocity high convinces you to say yes. > 氛围编程让你感觉自己拥有无限的实现预算。其实你并没有。你只是拥有无限的代码行数预算（AI 会根据你的要求生成任意多行代码）。但你的“复杂性预算”始终是有限的。架构只能支撑一定数量的功能，然后就会崩塌，不管你写得有多快。`CLAUDE.md` 中的范围控制，就是要在“高速开发的快感”诱导你说“好”之前，提前帮你说“不”。 --- **Tenet 4: Positional data is a time bomb.** > **准则 4：按位置存取数据是一颗定时炸弹。** Every resource in k10s was fetched from the Kubernetes API and immediately flattened: > k10s 中的每个资源在从 Kubernetes API 获取后，都会立刻被扁平化处理： ```go type OrderedResourceFields[]string ``` Column identity was purely positional. Here's the sort function for the fleet view. Look at the index access: > 列的身份标识纯粹依赖在数组中的位置。这是集群视图的排序函数。看看这些基于索引的访问： ```go func sortFilteredResources(rows []k8s.OrderedResourceFields, times[]time.Time, tab FleetTab) { sort.SliceStable(indices, func(a, b int) bool { ra := rows[indices[a]] rb := rows[indices[b]] switch tab { case FleetTabGPU: // Sort by Alloc column (index 3) ascending allocA, allocB := "", "" if len(ra) > 3 { allocA = ra[3] } if len(rb) > 3 { allocB = rb[3] } return allocA < allocB case FleetTabCPU: // Sort by Name column (index 0) ascending nameA, nameB := "", "" if len(ra) > 0 { nameA = ra[0] } if len(rb) > 0 { nameB = rb[0] } return nameA < nameB case FleetTabAll: // GPU nodes first, then CPU nodes. // Within GPU: sort by Alloc (index 3). // Within CPU: sort by Name (index 0). computeA, computeB := "", "" if len(ra) > 2 { computeA = ra[2] } if len(rb) > 2 { computeB = rb[2] } aIsGPU := strings.HasPrefix(computeA, "gpu") bIsGPU := strings.HasPrefix(computeB, "gpu") // ... } }) } ``` `ra[3]` is Alloc. `ra[2]` is Compute. `ra[0]` is Name. These are magic numbers. The only thing connecting index 3 to "Alloc" is a comment and the column order defined in `resource.views.json`: > `ra[3]` 代表分配（Alloc）。`ra[2]` 代表计算（Compute）。`ra[0]` 代表名称（Name）。这些全都是“魔法数字（Magic numbers，指代码中缺乏解释的硬编码数字）”。唯一把索引 3 和“Alloc”联系起来的东西，只有一行注释以及定义在 `resource.views.json` 中的列顺序： ```json { "nodes": { "fields":[ { "name": "Name", "weight": 0.28 }, { "name": "Instance", "weight": 0.15 }, { "name": "Compute", "weight": 0.12 }, { "name": "Alloc", "weight": 0.12 }, ... ] } } ``` Add a column between Instance and Compute? Every sort, every conditional render, every place that says `ra[2]` or `ra[3]` is now silently wrong. The compiler can't help you because it's all `[]string`. And the JSON config can't express sort behavior, conditional rendering, or custom drill targets, so those live in Go code that hardcodes the positional assumptions from the JSON. > 要在 Instance 和 Compute 之间加一列？那么每一次排序、每一次条件渲染、每一个写着 `ra[2]` 或 `ra[3]` 的地方，现在全都会悄无声息地出错。编译器帮不了你，因为一切都只是 `[]string` 类型。而且 JSON 配置无法表达排序行为、条件渲染或自定义的钻取目标，所以这些逻辑全留在了 Go 代码中，硬编码地继承了 JSON 中的位置假设。 AI generates this pattern because it's the shortest path from "fetch data" to "render table." A `[]string` satisfies any table widget immediately. Typed structs require more ceremony upfront. So the AI picks the fast path, and six months later you're debugging why sort puts "Name" values in the "Alloc" column. > AI 会生成这种模式，因为这是从“获取数据”到“渲染表格”的最短路径。一个简单的 `[]string` 能立刻满足任何表格组件的数据格式要求。而带有类型的结构体则需要更多的前期准备工作。所以 AI 选择了快车道，结果六个月后，你就得满头大汗地去调试为什么排序逻辑会把“Name”的值排到了“Alloc”的列里。 **What to do instead:** Put this directive in your `CLAUDE.md`: > **正确的做法：** 把这条指令放进你的 `CLAUDE.md` 中： ```markdown # Data Representation # 数据表示 - NEVER flatten structured data into[]string, Vec, or positional arrays. （绝不要将结构化数据扁平化为[]string、Vec 或按位置存取的数组。） - All data flows as typed structs (FleetNode, PodInfo, etc.) until the render() call. （所有数据流均以带类型的结构体形式流动，直到调用 render() 时为止。） - Column identity comes from struct field names, not array indices. （列的身份标识必须来自结构体字段名，而不是数组索引。） - Sort functions operate on typed fields, never on positional access like row[3]. （排序函数操作基于带类型的字段，决不能基于 row[3] 这样的位置访问。） - The ONLY place strings are created for display is inside render()/view() functions. （唯一允许生成用于展示的字符串的地方，是在 render()/view() 函数内部。） ``` Then your typed struct makes impossible states impossible [2]: > 然后，你那带有强类型的结构体就会让不可能的状态变得不可能发生[2]： ```rust struct FleetNode { name: String, instance_type: String, compute_class: ComputeClass, alloc: GpuAlloc, } ``` You can't sort by the wrong column when columns are named fields. You can't accidentally compare Alloc strings as names. The compiler enforces this for you. AI will always pick `Vec` because it satisfies the prompt faster. Your `CLAUDE.md` makes the typed path the path of least resistance. > 当列都被定义为命名字段时，你就不可能按照错误的列进行排序。你不可能一不小心把 Alloc 的字符串当成名称（Name）来比较。编译器会替你强制检查这一点。AI 总是会图快而选择 `Vec`，因为这满足提示的速度最快。你的 `CLAUDE.md` 护栏能让强类型路线变成新的“阻力最小路径”。 --- **Tenet 5: AI doesn't own state transitions.** > **准则 5：AI 无法掌控状态流转。** The Bubble Tea architecture has a beautiful idea: `Update()` is the only place state mutates, driven by messages. But k10s violated this. The `updateTableMsg` handler spawned a closure that mutated Model fields from inside a goroutine: > Bubble Tea 框架的设计架构中有一个极其优雅的理念：`Update()` 是状态发生变更的唯一场所，一切变更皆由消息（messages）驱动。但 k10s 违背了这一点。`updateTableMsg` 的事件处理器衍生出了一个闭包，居然直接从一个并发的 Goroutine（协程）内部修改了 Model 结构体的字段： ```go case updateTableMsg: return m, func() tea.Msg { // block on someone sending the update message. <-m.updateTableChan // Preserve cursor position across column/row updates so that // background refreshes don't reset the user's selection. savedCursor := max(m.table.Cursor(), 0) // run the necessary table view update calls. m.updateColumns(m.viewWidth) m.updateTableData() // Restore cursor, clamped to valid range. rowCount := len(m.table.Rows()) if rowCount > 0 { if savedCursor >= rowCount { savedCursor = rowCount - 1 } m.table.SetCursor(savedCursor) } return updateTableMsg{} } ``` This returned function (a `tea.Cmd`) is executed by Bubble Tea in a separate goroutine. It calls `m.updateColumns(m.viewWidth)` and `m.updateTableData()` which read and write `m.resources`, `m.table`, `m.viewWidth`. Meanwhile, `View()` is called on the main goroutine reading the same fields. There's no lock. No mutex. The channel `<-m.updateTableChan` blocks the goroutine until someone sends an update signal, but nothing prevents `View()` from reading half-written state. > 这个被返回的函数（即一个 `tea.Cmd`）由 Bubble Tea 在另一个独立的协程中执行。它调用了 `m.updateColumns(m.viewWidth)` 和 `m.updateTableData()`，这读取并写入了 `m.resources`、`m.table` 和 `m.viewWidth`。与此同时，主协程上正在调用 `View()` 渲染界面，读取的也是同一批字段。这里没有加锁（lock），没有互斥量（mutex）。`<-m.updateTableChan` 管道确实阻塞了协程直到有更新信号发来，但没有任何机制能阻止 `View()` 读取到只写了一半的脏状态数据。 This is a textbook data race. It worked 99% of the time. Corrupted the display 1% of the time in ways that made me think I was going insane. > 这是教科书级别的数据竞争（Data race）。它在 99% 的时间里都能正常工作。剩下的 1% 则会导致界面显示错乱，那抓马的现象简直让我怀疑自己是不是疯了。 AI generates this because "just mutate it in the closure" is the shortest path to working code. Proper message passing (send a message back to `Update()`, let `Update()` apply the mutation atomically on the main loop) requires more types, more plumbing. The AI is optimizing for the prompt, not for correctness under concurrency. > AI 生成这样的代码是因为，“直接在闭包里改变变量”是通向能跑的代码的最短路径。正确的消息传递方式（给 `Update()` 发回一个消息，让 `Update()` 在主循环中原子化地应用变更）需要定义更多的类型，铺设更多的底层管道代码。AI 纯粹是在为快速响应你的提示词做优化，而不是为了并发环境下的正确性做优化。 **What to do instead:** All mutations to render-visible state happen on the main loop. Period. Background workers produce data. They send it as a message. The main loop receives the message and applies it. This is the one rule you cannot break in concurrent UI code. > **正确的做法：** 所有对渲染可见状态的更改只能发生在主循环中。没有例外。后台工作线程负责生产数据。然后把数据作为一条消息发送出去。主循环接收该消息并应用变更。这是你在编写并发 UI 代码时唯一绝对不能打破的铁律。 ```rust // Background task: // 后台任务： tx.send(AppMsg::FleetData(nodes)).await; // Main loop: // 主循环： match msg { AppMsg::FleetData(nodes) => { self.fleet_view.update_nodes(nodes); } } ``` No shared mutable state. No data races. No "works 99% of the time." Put this in your `CLAUDE.md`: > 没有共享的可变状态。没有数据竞争。没有什么“99%的时间能工作”。把以下内容放进你的 `CLAUDE.md`： ```markdown # Concurrency Rules # 并发规则 - Background tasks (watchers, scrapers, API calls) NEVER mutate UI state directly. （后台任务绝对不可以直接修改 UI 状态。） - Background tasks send results through a channel as typed messages. （后台任务通过通道将结果作为强类型消息发送。） - Only the main event loop applies state mutations from received messages. （只有主事件循环才能应用来自接收消息的状态变更。） - render()/view() is a PURE function. No side effects. No I/O. No channel operations. （render()/view() 是一个纯函数。没有副作用。没有 I/O。没有通道操作。） - If you need to update state from async work, define a new AppMsg variant. （如果你需要根据异步任务的结果更新状态，定义一个新的 AppMsg 变体。） ``` If your AI doesn't generate this pattern by default, the directive makes it the only legal option. > 如果你的 AI 默认不生成这种模式，这个指令会强迫它把这当成唯一的合法选项。

IV

### what I'm doing differently now ### 我现在采取了哪些不同的做法 I'm rewriting k10s in Rust. Not because Rust is better but, because it's the language I can steer. I've written enough of it to feel when something's wrong before I can articulate why. That instinct is the one thing vibe-coding can't replace. The AI hands you plausible-looking code. You need a nose for when it's garbage. > 我正在用 Rust 重写 k10s。并不是因为 Rust 更好，而是因为这是我能完全掌控的语言。我写过足够多的 Rust，所以当我还没法清晰说出哪里不对劲的时候，我就能凭直觉感觉到问题所在。这种直觉是氛围编程唯一无法取代的东西。AI 会丢给你看似合理的代码。你需要有一种敏锐的嗅觉，去辨别它什么时候实际上是一堆垃圾。 The other change is simpler: I'm doing the design work myself, by hand, before any code gets written. Not a vague doc. Concrete interfaces, message types, ownership rules. The architecture decisions that the AI kept making wrong are now made in writing before the first prompt. Whether that's enough to keep the rewrite from collapsing under its own weight... I'll find out. > 另一个改变则更为简单：在写任何代码之前，我亲自、手工完成设计工作。不是写一份模棱两可的文档。而是具体的接口、消息类型、所有权规则。那些 AI 总是做错的架构决策，现在要在发出第一句提示词之前，以书面形式确立下来。这是否足以让重写的版本免于在自身的重量下再次崩塌……我会拭目以待的。 ### In the mean-time go star the TUI and show some love! ### 在此期间，去给这个 TUI 点个 Star 并表达下你的喜爱吧！ k10s Github K10S.DEV --- ### footnotes ### 脚注 [1][Bubble Tea](https://github.com/charmbracelet/bubbletea) is a TUI framework for Go based on The Elm Architecture. It's excellent. The architecture problems in k10s were mine, not Bubble Tea's. > [1] [Bubble Tea](https://github.com/charmbracelet/bubbletea) 是一个基于 Elm 架构的 Go 语言 TUI 框架。它非常优秀。k10s 里的架构问题是我一手造成的，不是 Bubble Tea 的问题。 [2] "Making impossible states impossible" is a phrase from Elm/Rust communities. The idea: design your types so that invalid states can't be constructed, rather than checking for invalid states at runtime. > [2] “让不可能的状态变得不可能发生（Making impossible states impossible）”是 Elm/Rust 社区的一句名言。其核心思想是：通过设计良好的数据类型，使得无效的状态从根本上无法被构造出来，而不是依赖在运行时再去检查无效状态。 [3] "You can totally go back now!" - realizing that the "smell of AI" writing bothers a particular group of people. It makes them dismiss the entire writing. Which is fair, so I wanna leave that crowd with the tl;dr and not waste their time. p.s. I personally don't see anything wrong with using AI in writing or illustrations etc. If your message is of any value, it will spread irrespective of any dialect smell. > [3] “你现在完全可以点返回键离开了！”——意识到 AI 写作的“味儿”会引起特定人群的反感。这会导致他们完全无视整篇文章。这很公平，所以我想直接给这群人提供“太长不看版（tl;dr）”，不浪费他们的时间。附言：我个人并不觉得在写作或插图中使用 AI 有什么错。只要你传达的信息有价值，无论带着怎样的“口音特征”，它都一定会传播开来。