feat(guide): add Section 9.18 - Codebase Design for Agent Productivity

Based on Agent Experience Best Practices by François Zaninotto (Marmelab).
Covers domain knowledge, code discoverability, testing for agents, guardrails.

- Add ~1809 lines to Section 9 (10 subsections)
- Enrich Section 3.1 with domain knowledge patterns
- Add Codebase Pitfalls to Section 9.11
- Bump version 3.9.11 → 3.10.0
- Guide grew from 11,560 to 13,425 lines (+16.1%)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

CHANGELOG.md

@@ -8,6 +8,43 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ---
 
+## [3.10.0] - 2026-01-21
+
+### Added
+
+- **Section 9.18: Codebase Design for Agent Productivity** (~1809 lines)
+  - **Based on**: [Agent Experience Best Practices](https://marmelab.com/blog/2026/01/21/agent-experience.html) by François Zaninotto (Marmelab, Jan 21, 2026)
+  - **Additional validation**: Netlify AX framework (2025), Speakeasy implementation guide, ArXiv papers on agent context engineering
+  - **9.18.1 Paradigm Shift**: Traditional vs AI-native codebase design, Agent Experience (AX) framework, when to invest in AX
+  - **9.18.2 Domain Knowledge Embedding**: CLAUDE.md advanced patterns, code comments (what vs how), Architecture Decision Records (ADRs)
+  - **9.18.3 Code Discoverability**: Complete terms vs abbreviations, synonyms in comments, JSDoc tags, directory READMEs
+  - **9.18.4 Token Efficiency**: Split large files (500 line guideline), remove obvious comments, verbose flags for debug output
+  - **9.18.5 Testing for Autonomy**: Why TDD is more critical for agents, tests written manually (not delegated), browser automation, coverage as guardrail
+  - **9.18.6 Conventions & Patterns**: Standard design patterns agents know, "boring tech" advantage, ADRs for custom architectures
+  - **9.18.7 Guardrails & Validation**: Hooks as anti-pattern validators, "tainted code" philosophy, PR reviews, validation layers
+  - **9.18.8 Serendipity & Cross-References**: Module cross-references, self-documenting commands, embedded technical docs
+  - **9.18.9 Usage Instructions**: Doc blocks with examples, Context7 MCP for official docs, sensible defaults
+  - **9.18.10 Decision Matrix**: When to optimize for agents vs humans, agent-friendly codebase checklist (33-point), quick wins
+- **Section 3.1 enrichment**: Added cross-reference to Section 9.18 for advanced domain knowledge patterns
+- **Section 9.11 new subsection**: "Codebase Structure Pitfalls" with ❌/✅ patterns and cross-reference to Section 9.18
+- **Table of Contents**: Added Section 9.18 entry
+- **Section 9 Recap**: Added "Codebase Design for Agents" item to quality awareness checklist
+- **machine-readable/reference.yaml**: Added `codebase_design_agents` entry with line number and source attribution
+
+### Changed
+
+- **VERSION**: Bumped from 3.9.11 to 3.10.0 (minor version bump for major new section)
+- **Guide size**: Increased from ~11,560 lines to 13,425 lines (+1,865 lines, +16.1%)
+
+### Context
+
+- **Gap identified**: Guide lacked comprehensive codebase design patterns for agent productivity
+- **Timing**: Article published 2 days ago (Jan 21, 2026), validated by Netlify AX research and ArXiv papers
+- **Target audience**: Teams extensively using Claude Code (>50% commits by agents), greenfield projects
+- **Complementary sources**: Netlify "Agent Experience" research, Speakeasy API DX guide (includes AX patterns)
+
+---
+
 ## [3.9.11] - 2026-01-21
 
 ### Added

README.md

@@ -169,7 +169,7 @@ Same agentic capabilities as Claude Code, but through a visual interface with no
 ```
 claude-code-ultimate-guide/
 ├── guide/                    # 📖 Core documentation
-│   ├── ultimate-guide.md     # Complete reference (~11550 lines)
+│   ├── ultimate-guide.md     # Complete reference (~13425 lines)
 │   ├── cheatsheet.md         # 1-page printable reference
 │   ├── architecture.md       # How Claude Code works internally
 │   ├── methodologies.md      # 15 development methodologies
@@ -328,7 +328,7 @@ Claude Code sends your prompts, file contents, and MCP results to Anthropic serv
 
 **Status**: Research preview (Pro $20/mo or Max $100-200/mo, macOS only, **VPN incompatible**)
 
-**Archive**: Historical versions available in git history (pre-v3.9.11)
+**Archive**: Historical versions available in git history (pre-v3.10.0)
 
 </details>
 
@@ -339,7 +339,7 @@ Claude Code sends your prompts, file contents, and MCP results to Anthropic serv
 
 | Repository | Purpose | Audience |
 |------------|---------|----------|
-| **[Claude Code Guide](https://github.com/FlorianBruniaux/claude-code-ultimate-guide)** *(this repo)* | Comprehensive documentation (11K lines, 65 templates) | Developers |
+| **[Claude Code Guide](https://github.com/FlorianBruniaux/claude-code-ultimate-guide)** *(this repo)* | Comprehensive documentation (13K lines, 65 templates) | Developers |
 | **[Claude Cowork Guide](https://github.com/FlorianBruniaux/claude-cowork-guide)** | Non-technical usage (67 prompts, 5 workflows) | Knowledge workers |
 | **Code Landing** *(to be deployed)* | Marketing site for Claude Code guide | Discovery |
 | **Cowork Landing** *(to be deployed)* | Marketing site for Cowork guide | Discovery |
@@ -397,7 +397,7 @@ Licensed under [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/).
 
 ---
 
-*Version 3.9.11 | January 2026 | Crafted with Claude*
+*Version 3.10.0 | January 2026 | Crafted with Claude*
 
 <!-- SEO Keywords -->
 <!-- claude code, claude code tutorial, anthropic cli, ai coding assistant, claude code mcp,

VERSION

@@ -1 +1 @@
-3.9.11
+3.10.0

guide/cheatsheet.md

@@ -6,7 +6,7 @@
 
 **Written with**: Claude (Anthropic)
 
-**Version**: 3.9.11 | **Last Updated**: January 2026
+**Version**: 3.10.0 | **Last Updated**: January 2026
 
 ---
 
@@ -411,4 +411,4 @@ where.exe claude; claude doctor; claude mcp list
 
 **Author**: Florian BRUNIAUX | [@Méthode Aristote](https://methode-aristote.fr) | Written with Claude
 
-*Last updated: January 2026 | Version 3.9.11*
+*Last updated: January 2026 | Version 3.10.0*

machine-readable/reference.yaml

@@ -3,8 +3,8 @@
 # Source: guide/ultimate-guide.md
 # Purpose: Condensed index for LLMs to quickly answer user questions about Claude Code
 
-version: "3.9.11"
-updated: "2026-01-20"
+version: "3.10.0"
+updated: "2026-01-21"
 
 # ════════════════════════════════════════════════════════════════
 # DEEP DIVE - Line numbers in guide/ultimate-guide.md
@@ -126,6 +126,10 @@ deep_dive:
   multi_instance_implementation: 9900
   multi_instance_monitoring: 9982
   multi_instance_decision_matrix: 10110
+  # Section 9.18 - Codebase Design for Agent Productivity
+  codebase_design_agents: 9942
+  codebase_design_source: "https://marmelab.com/blog/2026/01/21/agent-experience.html"
+  codebase_design_author: "François Zaninotto (Marmelab)"
   commands_table: 10179
   shortcuts_table: 10212
   troubleshooting: 10338
@@ -470,7 +474,7 @@ ecosystem:
       - "Cross-links modified → Update all 4 repos"
     history:
       - date: "2026-01-20"
-        event: "Code Landing sync v3.9.11, 66 templates, cross-links"
+        event: "Code Landing sync v3.10.0, 66 templates, cross-links"
         commit: "5b5ce62"
       - date: "2026-01-20"
         event: "Cowork Landing fix (paths, README, UI badges)"