AI 時代還需要軟體工程嗎？Clean Code 決定了 AI 戰力的天花板

Foreword: AI Makes Coding Faster, So Why Have Maintenance Costs Skyrocketed 4x?

In today's era of rapid development in generative AI and AI agents, many developers have experienced unprecedented development speed. With just a few prompts, AI can generate hundreds of lines of code in seconds, seemingly boosting development speed by 4x ¹⁰. However, as project scale grows, we're starting to observe a worrying phenomenon: the system's "Comprehension Debt" is quietly accumulating ¹⁰.

Many teams are finding that while coding is faster on day one, by the second year, system maintenance costs have soared to four times the original amount ¹⁰. This forces us to pause and ask: In the age of AI, do we still need software engineering? As engineers, do we still need to read and review code ourselves?

From our experience, AI has not yet reached the stage where "a single sentence can perfectly complete all complex tasks." Human-computer collaboration will remain the norm for a long time. If we feed bad code directly to AI, it will only produce more unmaintainable garbage code based on the existing chaos. As the industry says, "consistency" makes AI assistants a force multiplier, while "inconsistency" turns them into a chaos amplifier ¹⁰.

We've also reflected on this phenomenon in depth from a practical standpoint in Some Tips for Vibe Coding: AI is an Amplifier, Don't Let It Amplify Your Tech Debt.

Why "4x Faster" Never Shows Up in the Delivery Cycle

AI really does make implementation faster. But for a feature to go from idea to production, implementation was never the only cost. The real time sinks are requirement clarification up front and verification plus review at the back, and AI has barely reduced either of them. Verification has actually become more expensive.

The front half didn't get faster because AI can only execute what you have already articulated. The moment requirements are vague, AI simply produces off-target code faster, and you spend more time steering it back. The back half got more expensive because the code isn't yours: you have to read every line before you dare merge it, and AI produces far more code per pass than a human would, so the review burden scales up proportionally.

Based on how it feels on our own projects, the rough proportions look like this:

Loading diagram…

The bars are hand-written development, the line is with AI assistance. Implementation drops by three quarters, yet total effort falls by only a bit over ten percent, because most of what you save gets eaten by verification and rework. That is why so many teams feel that "AI is fast" while their delivery cycle barely moves.

Reading that chart tells you where the leverage actually is. What can be compressed is not typing speed, it is writing requirements and constraints in a form AI can read, and automating verification so that reviewers only look at what genuinely needs human judgement. Those two are exactly what the later sections on the "Context Constitution" and the "test guardrails" are about.

Core Pain Points: "Comprehension Debt" and Security Risks in the AI Era

Many people mistakenly believe that with tools like Copilot or Claude Code, code quality no longer matters. Some even think, "If I don't understand it, I'll just have the AI rewrite it." However, according to research from security and software institutes, this blind trust is creating huge risks:

4x Faster, 10x Riskier: Studies show that up to 62% of AI-generated code contains design flaws or known vulnerabilities, and projects using AI assistants have a 40% higher rate of secret (key) leakage ¹⁰. Even more alarmingly, 20% of packages recommended by AI don't even exist, which can easily lead to security crises like malicious package hijacking (Slopsquatting) ¹⁰.
Token Waste and Soaring Costs: When the codebase is chaotic and lacks optimization, the AI must read large amounts of useless code to understand the context, causing token consumption to skyrocket and development costs to soar ¹⁰.
Elongated Communication Chains, Low Efficiency: When code structure lacks cohesion and logic is scattered, the AI can't get the full context. You then have to spend more time explaining to the AI "why it needs to be written this way," drastically reducing human-computer communication efficiency ¹⁰.
Vulnerability Replication at Scale: A human developer might manually introduce a single security vulnerability, but an AI assistant can replicate that insecure design pattern across dozens of files at astonishing speed ¹⁰.

In the software development lifecycle, Operations Costs > Maintenance Costs > Development Costs. If we don't organize the architecture, the system will become completely unmanageable within three months. Currently, to modify any feature, engineers must have a sufficient understanding of the system to correctly guide the AI. This is why we mentioned in A Deep Dive into the Limitations of Vibe Coding that development without an architectural mindset will eventually hit a bottleneck.

Technical Solution: An AI-Friendly Architecture Centered on "Digital Asset Cohesion"

Faced with these challenges, we've found that "architecture" hasn't become obsolete with the advent of AI. On the contrary, architecture has become a context compression mechanism for AI ¹⁰. A good architecture helps AI filter out noise, significantly reducing its reasoning overhead ¹⁰.

1. Modular Monoliths Outperform Microservices

In AI collaboration scenarios, a microservices architecture can easily lead to "Context Fragmentation" ¹⁰. This is because microservices force an AI agent to understand multiple repositories, service boundaries, asynchronous messages, API contracts, and eventual consistency, which is extremely costly for AI to reason about ¹⁰.

In contrast, the modular monolith has a significant advantage. It concentrates highly cohesive business logic within a single project with clear boundaries, allowing AI to grasp the project's overall structure more quickly, reducing context fragmentation, and making transactional reasoning easier ¹⁰.

AI-Friendly Architecture Comparison Diagram

【高度碎片化的微服務架構】
┌──────────────┐   ┌──────────────┐   ┌──────────────┐
│  服務 A (Repo)│   │  服務 B (Repo)│   │  服務 C (Repo)│
└──────┬───────┘   └──────┬───────┘   └──────┬───────┘
       │                  │                  │
       └───────────► 異步訊息 / API ◄────────┘
  ⚠️ AI 必須理解多個 Repository、服務邊界、API 契約與最終一致性
  ❌ 缺點：Context 嚴重碎片化、Token 消耗極大、推理錯誤率高

【高內聚的模組化單體架構 (Modular Monolith)】
┌────────────────────────────────────────────────────┐
│ 單一 Repository (共享 Context 邊界)                 │
│  ┌──────────────┐   ┌──────────────┐   ┌─────────┐ │
│  │  模組 A (Domain)│ ◄─│  模組 B (Domain)│ ◄─│CLAUDE.md│ │
│  └──────────────┘   └──────────────┘   └─────────┘ │
└────────────────────────────────────────────────────┘
  ✅ 優點：AI 載入單一專案即可取得完整脈絡、邊界清晰、交易推理簡單

2. Clean Code Guidelines as AI "Performance Settings"

In the age of AI, code quality is no longer just an engineer's aesthetic preference; it directly determines the ceiling of an AI's effectiveness ¹⁰. To enable AI to get code changes right in one or two attempts, we recommend implementing the following standards in your project ¹⁰:

Strictly Limit Complexity: Set the maximum Cyclomatic Complexity for a single function to 12 and the maximum file length to 400 lines ¹⁰. Long files distract the AI.
Forbid Vague Naming: Strictly prohibit generic and ambiguous names like utils, helpers, and common ¹⁰. Such names prevent the AI from quickly determining responsibilities, leading to misplaced code.
Strong Typing Constraints: Disable the any type in TypeScript projects ¹⁰. Complete type definitions are the best navigation guide for an AI.

3. How Does the Industry Actually Enforce Coding Standards? Turning Standards from "Documents" into "Toolchains"

After decades of promoting coding standards, the industry has distilled its consensus into a single sentence: a standard that only lives in a wiki doesn't exist. Standards that rely on personal discipline are always the first thing sacrificed under schedule pressure; the standards that survive are the ones baked into the toolchain and enforced automatically, an approach commonly known as "Standards as Code." Mainstream teams organize this into six layers:

Layer	Mainstream Tools	What It Catches
Style Guides	Google Style Guides, Airbnb JavaScript, PEP 8, .NET Conventions	A shared language for naming and idioms
Formatter	Prettier, Black, gofmt	Every argument about indentation, quotes, and line breaks
Linter	ESLint, Ruff, Roslyn Analyzers	Excessive complexity, vague naming, dangerous syntax
Type Checking	TypeScript `strict`, mypy	Type errors, implicit `any`
Architecture Guards	dependency-cruiser, ArchUnit, NetArchTest	Illegal cross-module dependencies, circular dependencies
Gatekeeping	husky + lint-staged, CI Quality Gate (SonarQube)	Substandard code never reaches commit / merge

A few practical takeaways:

Adopt public style guides instead of inventing your own: Google, Airbnb, and PEP 8 have been battle-tested by thousands of teams; adopting them directly saves endless style debates. There's also a hidden bonus for AI collaboration: these guides are heavily represented in the models' training data, so following mainstream conventions means "speaking the language the AI knows best," and the generated code will match your expectations more closely.
Let the formatter end format debates: The value of opinionated formatters like Prettier is precisely that "there's nothing to argue about"; formatting issues disappear from code review forever.
The rules from the previous section must become linter rules: Cyclomatic complexity of 12, 400 lines per file, no any, no vague naming. These can't just live in a document; let the tools enforce them:

// eslint.config.js: turning Clean Code standards into executable rules
export default [
  {
    rules: {
      complexity: ['error', { max: 12 }], // cyclomatic complexity cap of 12
      'max-lines': ['error', { max: 400 }], // 400-line cap per file
      '@typescript-eslint/no-explicit-any': 'error', // no `any`
      'id-denylist': ['error', 'utils', 'helpers', 'common'], // no vague naming
    },
  },
]

Architecture boundaries can be tests too: Principles like "the Domain layer must never depend on the Infrastructure layer" can be written as automated tests with dependency-cruiser (JS/TS), ArchUnit (Java), or NetArchTest (.NET); any violation turns CI red.
Set up two gates: Locally, husky + lint-staged intercepts before every commit; then CI applies a Quality Gate (e.g., SonarQube thresholds on new-code duplication, coverage, and vulnerabilities) as the second gate. Substandard PRs never reach the mainline.

For AI collaboration, this toolchain has an amplifying effect: linter error messages are real-time feedback the AI can read. After an AI agent edits code, one lint run returns violations as explicit error messages the AI can immediately self-correct against, a correction loop that a wiki-bound standard can never provide.

Implementation Steps: Building a "Context Infrastructure" and Human-AI Collaboration Workflow

To make AI a true productivity tool, we must proactively build the project's "Context Infrastructure" ¹⁰. Here are our recommended implementation steps:

Step 1: Create a "Context Constitution" Document

Create a CLAUDE.md or a dedicated context file in the project's root directory. This document serves as the "project manual" for the AI agent, clearly defining architectural principles, the tech stack, and development standards.

According to an analysis report by Anthropic, teams that maintain good context documents see a 40% reduction in AI errors and a 55% increase in task completion speed ¹⁰.

A Standard `CLAUDE.md` Template

Below is a CLAUDE.md template suitable for a TypeScript project, which you can place directly in your project's root directory:

# CLAUDE.md - 專案開發憲法

## 專案簡介
本專案為一個基於 Node.js / TypeScript 的電子商務後端系統，採用模組化單體（Modular Monolith）架構。

## 技術堆疊
- 執行環境：Node.js v20+
- 語言：TypeScript v5+
- 框架：NestJS
- 資料庫：PostgreSQL (Prisma ORM)

## 常用指令
- 安裝依賴：`npm install`
- 啟動開發伺服器：`npm run start:dev`
- 執行單元測試：`npm run test`
- 執行整合測試：`npm run test:integration`
- 程式碼格式化：`npm run format`

## 程式碼風格與架構約束
- **架構模式**：嚴格遵循 Domain-Driven Design (DDD) 與高內聚原則。
- **命名規範**：
  - 禁止使用 `utils`、`helpers`、`common` 等模糊命名，請依業務邏輯命名（例如：`PaymentCalculator`、`EmailNotifier`）。
- **類型系統**：
  - 嚴格禁用 `any` 類型，所有變數與函式必須有明確的型別定義。
- **複雜度限制**：
  - 單一函式複雜度（Cyclomatic Complexity）上限為 12。
  - 單一檔案程式碼長度上限為 400 行。超過時必須進行模組化拆分。
- **錯誤處理**：
  - 統一使用自定義的 `AppError` 類別，禁止直接拋出未捕獲的 Generic Error。

Step 2: Use the `.claude/` Folder to Upgrade Standards into AI Behavioral Constraints

CLAUDE.md is only the entry point. Claude Code's .claude/ folder provides a whole set of mechanisms that upgrade team standards from "reference documents" into "behavioral constraints". Since these files live in version control, the entire team (humans and AI alike) shares the same standard:

Mechanism	Location	When It Loads	What Belongs There
Rules	`.claude/rules/*.md`	Automatically, every conversation	Non-negotiable team laws
Custom Commands	`.claude/commands/*.md`	When the user types `/command`	Standardized, repeatable workflows
Skills	`.claude/skills/*`	When the AI deems the task relevant	Domain-specific playbooks
Hooks	`.claude/hooks/` + `settings.json`	Before/after tool calls (shell level)	Hard interception the AI cannot bypass

The constraint strength of these four layers is increasing. Using my own blog project's actual setup as an example:

Rules (soft constraints): Rules placed in .claude/rules/ enter the AI's context in every conversation. My project includes spec-before-code.md (a spec document must be created and confirmed before touching code) and cache-versioning.md (every AI-generated static asset URL must carry a version query for cache-busting). The AI actively follows them, but at heart they are still "reminders."
Commands / Skills (workflow standardization): Multi-step workflows like "write an article," "create a spec," or "deploy" become commands and skills such as /write-blog, /create-spec, and /deploy, so everyone, including the AI itself, executes exactly the same steps, eliminating the chaos of "everyone does it differently." Skills have the added benefit of loading on demand: the AI reads them only when the task is relevant, wasting no context.
Hooks (hard constraints): This is the critical layer. Hooks are shell-level scripts that can intercept and inspect before the AI invokes tools like Edit/Write. For example, my project has a PreToolUse hook: when docs/specs/pending/ contains no spec document, it outright blocks the AI from modifying code files and returns a "please create a spec first" message. This is the same philosophy as linters blocking human commits: standards are enforced by interception, not by self-discipline.

In other words, the .claude/ folder is the extension of "Standards as Code" into the age of AI collaboration: linters constrain the code humans write, .claude/ constrains the AI's behavior, and only together do they form a complete safety net.

Step 3: Implement Automated Testing as a "Guardrail"

Code generated by AI must have an objective verification mechanism. Unit and integration tests are the best "guardrails." Before a comprehensive automated testing system is in place, we strongly recommend that human engineers perform manual testing and final checks. Never let the AI deploy on its own.

This echoes what we mentioned in AI is Diligent, But It Doesn't Understand What You're Doing: Practical Reflections from Multi-Agent to Vibe Coding: AI development without testing guardrails is like bungee jumping without a safety cord.

Step 4: Establish Risk-Based Code Review Guidelines

Even if AI writes most of our code, human reading and review remains indispensable. But review shouldn't be an all-or-nothing choice between "read everything" and "read nothing"; review depth should be proportional to the cost of being wrong. In practice, start by asking yourself three questions:

If this code is wrong, what's the cost? (Financial loss, a data breach, or just a broken layout?)
Can a failure be rolled back quickly? (One-click revert, or is the data already corrupted beyond recovery?)
Will this code be continuously extended and maintained? (The longer code lives, the more quality compounds.)

Based on the answers, handle AI-generated code according to three risk tiers:

Risk Tier	Typical Scope	Review Approach
High Risk	Security, payments, access control, personal data handling, data migration and deletion, external API contracts	Line-by-line review, with a second reviewer when necessary; never merge directly
Medium Risk	Core business logic, system architecture and module boundaries, code that will be extended and maintained long-term	Focus the review on whether the design and boundaries are correct; let tests guard the implementation details
Low Risk	One-off scripts, internal tools, UI style tweaks, proof-of-concepts	Let automated tests and linters do the gatekeeping, with occasional human spot checks

Precautions and Risks

When introducing AI collaboration, we need to pay special attention to the following points:

Cognitive Risk: If engineers "don't know the 'why' behind their work" and just blindly copy-paste AI-generated code, they will gradually lose control over the system. When an unexpected error occurs, humans will be completely unable to debug it.
Inaction is the Biggest Risk: Although AI introduces the risk of technical debt, refusing to adopt AI tools or refactor old systems for fear of making mistakes often leads to a greater risk of being outcompeted in this era of rapid technological iteration.
The Trap of Over-Delegation: Currently, AI can only be fully delegated 0% to 20% of simple tasks. The remaining 80% of the work still requires human engineers for context management and system design ¹⁰. Never treat AI as a panacea that allows you to completely wash your hands of responsibility.

Conclusion: Efficiency = Human Architectural Thinking + AI Execution Power

Returning to the initial question: Do we still need software engineering in the age of AI?

The answer is: More than ever before.

The more cohesive your digital assets, the more power AI can unleash ¹⁰. Conversely, a chaotic architecture will only turn AI into a technical debt accelerator. Software engineering hasn't disappeared; it has transformed into "how to prepare clean context and architecture for AI" ¹⁰.

When we can guide AI with a clear architecture, standardize it with CLAUDE.md, and constrain it with automated tests, only then can we truly unlock AI's potential and achieve an efficient and secure development model. On this topic, I recommend reading Rethinking the Value of Software Engineering in the AI Era, which has more discussion on transforming development mindsets.

Next Step: Add a CLAUDE.md to your project today, encode your Clean Code standards into your linter config and .claude/rules/, and try refactoring those chaotic modules that frequently cause AI to make mistakes!