The AI Coding Manifesto: Building Scalable Codebases

This manifesto outlines a strategy for maintaining codebase integrity when working with AI coding agents. It advocates for a strict separation between minimal, pure 'semantic' functions and complex 'pragmatic' wrappers. By also enforcing data models that make invalid states impossible, developers can ensure their code remains scalable and resistant to decay.

Key Points

• Semantic functions should be minimal, pure, and self-describing building blocks that require no comments and are easily unit-testable.
• Pragmatic functions serve as wrappers for complex, changing processes and should be documented with context rather than just restating the function name.
• Data models must be designed to make invalid states impossible, utilizing precise naming and brand types to prevent silent logic errors.
• Codebase degradation occurs when the boundaries between semantic and pragmatic logic blur or when models are bloated with optional fields for convenience.
• Intentional architectural patterns are essential to prevent AI coding agents from rapidly creating a 'sloppy' and unscalable codebase.

Sentiment

The Hacker News community broadly agrees with the article's central message that developers need intentionality when using AI coding tools. However, many commenters feel the ideas are well-established software engineering principles repackaged for the AI era rather than genuinely novel insights. There is a constructive debate about the limits of codifying quality and whether linters alone can solve the problem.

In Agreement

• AI lowers the friction to adding code faster than teams can properly absorb it, causing subtle erosion of codebase consistency rather than obvious bugs
• Optional field bloat from AI agents is a serious design problem — each optional parameter spreads decision-making across the codebase instead of centralizing it
• Developers must take full responsibility for AI-generated code quality; submitting AI output for review means personally vouching for it
• Clean, well-structured codebases serve as better prompts for AI agents — agents follow existing patterns in clean repos but invent new ones in messy ones
• Linters, pre-commit hooks, and automated enforcement tools are effective guardrails for constraining AI to follow conventions

Opposed

• The manifesto's principles are not specific to AI — optional field bloat, poor abstractions, and design erosion are problems humans have always created
• The semantic vs. pragmatic function distinction is too vague — the established functional core / imperative shell pattern expresses the same idea more clearly
• Code quality cannot be fully codified into deterministic rules — the hardest aspects like useful abstractions and intuitive design remain fundamentally subjective
• The article's own website is broken on mobile Safari, which undermines the manifesto's credibility about intentional AI-assisted development