Code Best Practices — The Clean Code & Clean Architecture Rulebook for AI Coding Agents
Turn Claude Code, Cursor, Codex, Copilot, Gemini CLI, Windsurf, and Aider into disciplined senior engineers — with one drop-in instruction pack.AI coding agents are fast. They are not careful. Left to their defaults, they produce 400-line functions, God classes, framework code tangled into business logic, comments instead of good names, and dependency graphs that point every direction at once. You end up reviewing, rejecting, and re-prompting — paying twice for code you should only pay for once.Code Best Practices fixes the root cause: your agent has no engineering standard. This pack gives it one — 17 tightly-written Markdown instruction files that distill two of the most influential software engineering books ever written into rules an AI agent can actually load, follow, and be reviewed against: Martin, Robert C. Clean Code: A Handbook of Agile Software Craftsmanship. Prentice Hall, 2008. Martin, Robert C. Clean Architecture: A Craftsman's Guide to Software Structure and Design. Prentice Hall, 2017. Decades of hard-won engineering judgment, normalized into a compact, token-efficient operating standard — written specifically for the way AI CLI agents consume context.What you get17 instruction files. One rule per file. Zero duplicated context. 01 — Core Principles — the Boy Scout Rule, the Dependency Rule, the two values of software, Simple Design, and a decision-priority table for when rules conflict 02 — Naming — names that reveal intent, are searchable, and never lie 03 — Functions — small, one thing, one abstraction level, ≤3 arguments, no flag parameters 04 — Comments & Formatting — comments as a last resort; structure that shows itself 05 — Objects & Data Structures — objects vs. data, the Law of Demeter, no train wrecks 06 — Error Handling — exceptions with context, no null returns, special-case objects 07 — Boundaries & Dependencies — wrap vendors, pin third-party behavior with learning tests 08 — Testing — TDD discipline, tests as documentation, one concept per test 09 — Classes & SOLID — all five principles, applied rather than recited 10 — Architecture — entities, use cases, adapters, and the Dependency Rule enforced in practice 11 — Components & Packaging — cohesion and coupling principles, no dependency cycles 12 — Concurrency — threads, async, and shared state without the footguns 13 — Refactoring Workflow — safe, test-guarded micro-steps for legacy code 14 — Smells Checklist — a coded catalog of code smells for fast, repeatable review sweeps 15 — AI Agent Playbook — the crown jewel: a behavior contract, a standard agent workflow, copy-paste prompts for common tasks, and acceptance checklists 16 — References — full MLA citations plus vetted supporting sources (Fowler, Beck, Feathers, Evans, and more) README — master instructions, a per-task file map, and a token/context loading strategy How it works Drop the folder into your repo. One directory, plain Markdown, no build step, no runtime, no lock-in. Wire it into your tool's instruction file. The README maps every major agent to its mechanism: AGENTS.md for Codex/Cursor/Jules, CLAUDE.md imports for Claude Code, GEMINI.md for Gemini CLI, .github/copilot-instructions.md for Copilot, .windsurf/rules/ for Windsurf, CONVENTIONS.md for Aider — and a forward-compatible path for tools that don't exist yet. The agent loads only what the task needs. Renaming? It loads the naming file. Touching a vendor SDK? Boundaries. Designing a service? Architecture. Each rule lives in exactly one file, so you never burn tokens on duplicated context — the pack was engineered around context windows from day one. Review against the checklist. The smells catalog and agent playbook give you coded, repeatable acceptance criteria — so "looks fine to me" becomes "passes C3, E1, and the Dependency Rule check." Why this beats prompting harder Consistency you can't get from prompts. A prompt is advice for one conversation. An instruction pack is a standard for every conversation, every branch, every teammate, every tool. Token-efficient by design. Most "rules" repos dump entire books into context. This pack is a normalized distillation — always-load core of about one page, then one or two topic files per task. Your context window stays for your code. Architecture, not just style. Linters catch formatting. Nothing else in your toolchain tells an agent that business rules must not import the framework, that dependencies point inward, or that a boundary decision should be deliberate and recorded. This does. Built for review, not just generation. The coded smells checklist and copy-paste review prompts turn code review of AI output from a vibe check into a procedure. Tool-agnostic and future-proof. Switch from Cursor to Claude Code to whatever ships next year — the standard travels with the repo, not the tool. Who it's for Solo developers and freelancers shipping client work with AI assistance who can't afford to deliver a mess Tech leads and architects who need every agent (and every developer driving one) held to the same standard Teams adopting AI coding tools that want velocity without a rewrite-it-later mortgage IT staff and consultants maintaining long-lived systems where structure matters more than speed Anyone who read Clean Code and Clean Architecture and wants their agent to have read them too What changes in your output Functions that do one thing, at one level of abstraction, with honest names Business logic that's testable without a database, framework, or network Vendors and third-party APIs wrapped behind adapters instead of leaking everywhere Errors handled with context — no swallowed exceptions, no null-return roulette Tests that read like documentation and verify one concept each Refactors executed in safe, behavior-preserving micro-steps — never a risky big-bang rewrite Agents that report what changed, in which layer, and which dependencies were created or inverted Frequently asked questionsDoes this include the books?No. This is an original, independently written distillation of the principles — normalized, deduplicated, and reformatted for AI agent consumption, with full MLA citations and a curated further-reading list. For the authors' complete wording, figures, and code listings, buy the books (you should — they're referenced above).Which languages does it cover?The rules are language-agnostic — they govern naming, structure, dependencies, and testing discipline, which apply in Python, TypeScript, C#, Java, Go, and everything else. The references file also links vetted per-language adaptations.Will it eat my context window?The opposite — that's the point. The loading strategy is: one ~1-page core always, one or two topic files per task, checklists only at review time. It's dramatically leaner than pasting style guides or book notes into your prompts.What if my tool isn't listed?Every current agent supports some form of project instruction file, and the pack follows the open AGENTS.md convention. Point your tool's instruction mechanism at the pack and it works.Format and delivery?Instant digital download: 17 plain Markdown files plus master README. No DRM, no accounts, no dependencies. Use it in unlimited personal and client projects.Stop reviewing messes. Start shipping clean.Every session your agent runs without a standard is more code you'll pay to fix later. Robert C. Martin spent decades codifying what clean code and clean architecture mean — this pack puts that discipline inside your AI tools today, for less than the cost of one hour of cleanup.Download Code Best Practices now → drop it in your repo → your next agent session already writes better code.References (MLA)Martin, Robert C. Clean Code: A Handbook of Agile Software Craftsmanship. Prentice Hall, 2008.Martin, Robert C. Clean Architecture: A Craftsman's Guide to Software Structure and Design. Prentice Hall, 2017.This product is an independent educational distillation and is not affiliated with, endorsed by, or sponsored by Robert C. Martin or Pearson/Prentice Hall. The books themselves are not included.
Get it → chriszenzel.gumroad.com