AI Coding Lessons from Building k10s: Why Architecture Matters
Refactor k10s to isolate view state, add architecture invariants to CLAUDE.md, and test view transitions to prevent data bleed.
Refactor k10s to isolate view state, add architecture invariants to CLAUDE.md, and test view transitions to ensure no data bleed.
Summary
k10s v0.4.0, a GPU‑aware Kubernetes dashboard, was built entirely with Go and Bubble Tea over 7 months and 234 commits, using Claude for feature generation. The project started with a simple k9s clone, adding pods, nodes, deployments, services, and a command palette, then expanded to a dedicated GPU fleet view that displays allocation, utilization, temperature, power draw, and memory in a color‑coded table.
However, Claude’s tendency to create a single “god object” caused the entire state to live in a 1690‑line Model struct, with a 500‑line Update method and 110 switch/case branches. Manual nil assignments scattered throughout the file led to data bleed between views, breaking live updates and causing stale data. The author realized that AI builds features, not architecture, and that without clear invariants the codebase devolves.
The key takeaway is to write concrete architecture rules—such as view isolation, message‑only data flow, and no cross‑view state mutation—before prompting Claude. These rules should be documented in CLAUDE.md or AGENTS.md so the AI follows them. By doing so, developers can harness AI for rapid feature delivery while maintaining a clean, maintainable codebase.
Key changes
- k10s v0.4.0 built with Go and Bubble Tea
- GPU fleet view shows allocation, utilization, temperature, power draw, memory
- Claude generated a 1690‑line Model struct with 500‑line Update method
- Manual nil assignments caused data bleed between views
- AI builds features but not architecture, leading to a god object
- Architecture invariants must be defined in CLAUDE.md
- View isolation prevents cross‑view state mutation
- Testing view transitions ensures no stale data