LLM Wiki — Synaptic Lattice

code-complete

Properties1
tagsvibe-coding, technical-literacy, specification

Leitura de 8 min

Code Complete — disciplina de construção

Definition

Este conceito destila o livro code-complete em regras executáveis para agentes de IA, conforme publicado no repositório agent-rules-books (v0.5, MIT, fork de ciembor/agent-rules-books). Cada livro tem 3 formatos (full canônico, mini recomendado, nano compacto); esta página documenta o mini — o formato usado no dia a dia para instruir Codex, Cursor e Claude Code sem estourar a janela de contexto.

Ponto de partida: Code Complete — disciplina de construção. Ver detalhes completos do mini na seção “Regras originais (mini)” abaixo, extraída verbatim de raw/vibecoding/articles/agent-rules-books.md.

Quando usar

Extraído do header ## When to use do mini (tradução e adaptação para founder/PM não-técnico abaixo; original em inglês mantido na seção final):

  • Use quando a dimensão que este livro governa for o risco principal da tarefa do agente (legibilidade, arquitetura, legado, dados, etc.).
  • Prefira este livro como contrato verificável em vez de pedir genérico tipo “faça bem feito” — ver hub regras-de-agentes-a-partir-de-livros para escolher entre os 14.

Viés principal a corrigir e regras de decisão

O mini organiza as regras em ## Primary bias to correct e ## Decision rules. Para o founder, isso vira checklist de revisão do plano e do PR:

  • Leia o Primary bias como o erro que o agente comete quando só recebe instrução vaga (ex.: “código que roda não é código limpo” em Clean Code; “complexidade acidental” em Philosophy of SD).
  • Transforme cada Decision rule em critério de pronto da issue (especificacao-de-issues-para-agentes) e em item do Final checklist que você cobra no review.

Consulte a transcrição completa na seção final e marque na issue quais regras desta página se aplicam (ex.: scoped rules só em src/domain/** para DDD, só em src/infra/** para Release It!).

Gatilhos (Trigger rules)

Os Trigger rules do mini indicam quando o agente deve quebrar a tarefa em passos menores ou trocar de padrão (ex.: “quando função mistura setup/validação/computação/efeito, separe fases” — Clean Code; “quando boundary vaza framework para dentro, fortaleça adapter” — Clean Code/Clean Architecture). Para o founder, são sinais para pedir ao agente: “pare, proponha plano antes de codar” (plan-first-com-agentes-de-ia).

Checklist final para o founder cobrar do agente

O mini fecha com ## Final checklist — perguntas que você faz no PR sem precisar ler o livro:

  • O leitor consegue seguir a mudança localmente, sem pular arquivos?
  • Nomes/APIs carregam significado sem comentário narrativo?
  • Mutação é explícita e o caminho feliz permanece legível?
  • Detalhes de framework/persistência/vendor ficaram atrás de boundaries?
  • Pelo menos um smell foi removido na área tocada, sem alargar o escopo silenciosamente?
  • Testes protegem o contrato mudado e foram efetivamente rodados?

Adapte o checklist ao livro: para DDIA troque por “timeout/retry/circuit breaker definidos?”; para DDD troque por “linguagem ubíqua respeitada? aggregate protege invariantes?”.

Implications

Para o founder/PM não-técnico, esta página transforma conhecimento de livro — normalmente inacessível sem 300+ páginas de leitura — em instrução operacional colável no AGENTS.md/skills. Em vez de torcer para o agente “saber” o livro, você cola 30 regras testáveis e mede no vibe-coded-crap (74/100 com mini vs 46/100 só citando o título). Isso conecta agents-md-como-instrucao-operacional (zona 60-150 linhas, pointers), plan-first-com-agentes-de-ia (plano melhora com regras concretas) e ciclo-issue-branch-pr-merge (PR só mergea se passa no checklist).

Regras originais (mini) — transcrição verbatim

Fonte: raw/vibecoding/articles/agent-rules-books.md seção ## code-complete — conteúdo mini extraído via https://raw.githubusercontent.com/mattpocock/agent-rules-books/main/code-complete/code-complete.mini.md em 2026-08-29. Transcrição fiel; não substitui a leitura do livro.

OBEY Code Complete by Steve McConnell
 
## When to use
 
Use when implementing, changing, reviewing, debugging, refactoring, or tuning production code where construction discipline must reduce defects and keep code easy to inspect.
 
## Primary bias to correct
 
Construction quality is not accidental. Do not treat typing code, making it work once, or using a clever idiom as complete construction; choose the option that lowers defect risk and makes the code easier to reason about.
 
## Decision rules
 
- Before large construction work, verify that requirements, architecture, major risks, coding conventions, language constraints, error policy, data representation, reuse, integration, and testing approach are clear enough.
- When upstream uncertainty remains, build a small validated slice instead of speculative code, and make expensive-to-reverse decisions deliberately.
- Optimize first for human readers: clarity, locality, explicitness, visible control flow, consistent conventions, and practical correctness over cleverness, minimal keystrokes, or fashion.
- For complex routines, sketch precise pseudocode or intent comments at a consistent abstraction level, then convert them into code and keep only comments that still explain intent, constraints, contracts, or rationale.
- Keep routines cohesive, precisely named, small at the interface, and hard to misuse. Separate setup, validation, computation, and side effects when they are conceptually different.
- Make variable and data meaning explicit through purpose-revealing names, small scope, deliberate initialization, named constants, stronger types, and visible units or sentinel meanings.
- Choose data types that make invalid or ambiguous values harder to represent; use booleans only for true binary meanings, enumerations for closed sets, and records/maps/tables only when their shape communicates meaning.
- Keep control flow simple enough to verify: shallow nesting, named predicates for complex conditions, clear normal path, clear loop initialization/termination/update, and no side-effect-dependent expressions or clever one-liners.
- Use table-driven or data-driven logic for stable explicit mappings only when the table is clearer, obvious, synchronized with the rules, and validated; do not hide complex behavior in inscrutable encodings.
- Validate input at trust boundaries. Use assertions, invariant checks, and simple contracts for programmer assumptions; use validation or domain errors for expected external or business failures.
- Handle errors at the right abstraction, preserve diagnostic context, standardize similar failures, keep the normal path readable, and never silently continue from corrupted or impossible state.
- Keep classes and modules focused, cohesive, and bounded by clear contracts; hide representation and internal bookkeeping, and avoid mixed persistence, formatting, business, and integration concerns.
- Treat rising complexity as defect risk: split tangled routines or modules, remove duplication that multiplies maintenance effort, and reduce what a maintainer must keep in working memory.
- Build in small, verifiable increments; integrate often enough to expose conflicts, keep partial work from rotting, and review and improve code during construction.
- Match reviews, inspections, pair work, tests, static checks, and regression tests to defect risk. Debug by reproducing, isolating, explaining, fixing, and verifying root causes rather than guessing.
- Refactor when structure hides intent, duplicates knowledge, or raises defect probability, and keep refactoring separate from behavior change when that improves reviewability.
- Tune performance only when requirements and evidence justify it; measure before and after, and keep clarity unless an explicit measured tradeoff warrants the cost.
- Use tools, scripts, debuggers, profilers, editors, and build automation to reduce error-prone manual work, not to replace understanding.
- Use layout, comments, documentation, and coding standards to lower reader effort. Prefer self-documenting structure first; comments should explain intent, assumptions, constraints, limitations, usage, or non-obvious facts.
 
## Trigger rules
 
- When coding starts from a proposed solution, restate the requirement, architecture fit, risks, conventions, and success constraints before implementation.
- When a routine is hard to name, mixes phases, has flag arguments, long parameters, or hidden side effects, redesign the interface or split the routine.
- When readers must decode units, ranges, precision, encoding, ownership, status, magic values, or primitive flags, move that meaning into names, constants, types, or structures.
- When input crosses a user, file, network, external-system, or other trust boundary, decide what is validated, rejected, recovered from, asserted, and kept diagnosable.
- When branches, loops, recursion, exits, or exception paths become hard to verify, simplify before adding logic.
- When repeated branching maps stable categories, ranges, conversions, validation, dispatch, or configuration-like rules, consider a validated table.
- When a class or module exposes representation, grows into a god object, or mixes unrelated responsibilities, restore the abstraction boundary.
- When tests cover only the happy path, add normal, boundary, invalid-input, defensive-check, routine-contract, and data-driven edge cases.
- When debugging begins from a guess, first make the failure repeatable, collect evidence, isolate the path, and explain the cause.
- When refactoring poorly understood or risky code, add tests or analysis first and keep behavior changes separate.
- When performance work begins, set a target, measure the current behavior, change one thing, remeasure, and document any clarity tradeoff.
- When comments restate obvious mechanics or go stale, rewrite the code or delete the comment; when code cannot express intent, constraints, or usage, add a close accurate comment.
- When local style starts to diverge, follow shared formatting, naming, file-structure, and idiom conventions instead of creating a module-specific dialect.
 
## Final checklist
 
- Requirements, architecture fit, risks, conventions, and construction approach are clear enough.
- Names, routines, data, classes, layout, comments, and standards reduce reader effort.
- Inputs, errors, assertions, contracts, invariants, impossible states, and trust boundaries are deliberate.
- Control flow, loops, tables, recursion, exits, and exception paths are simple enough to inspect.
- Tests, reviews, debugging, refactoring, integration, tooling, and tuning are evidence-based.
- The change is small enough to verify and would stand up to careful review.

Sources

Visão de gráfico

Backlinks