Skip to content

overview.md

Latest commit

 

History

History
96 lines (71 loc) · 6 KB

overview.md

File metadata and controls

96 lines (71 loc) · 6 KB
Raw

Overview

What Is an Agentic-Ready Codebase?

An agentic-ready codebase provides AI coding agents with the structure they need to work safely and accurately:

  • Focused and reliable context — agents reason over relevant information, not the entire repo.
  • Clear interfaces and relationships — boundaries are explicit, not implicit.
  • Deterministic development commands — one command surface (format, format:check, lint, typecheck, test, check, security, realised as package scripts, a Taskfile, or a Makefile) produces identical results for agents, humans, and CI.
  • Executable quality gates — automated checks that agents must pass before changes are accepted.
  • Tests that protect existing behavior — characterization tests, contracts, and unit tests.
  • Documentation that evolves with the code — generated, maintained, and indexed automatically.
  • Security and change-control boundaries — agents operate within defined constraints.

Important

Applicability

Codebase Type Supported Notes
Monoliths ✅ Primary target
Monorepos ✅ Supported with component-level scoping (component scoping: v0.3)
Microservices ⚠️ Not explicitly validated but no architectural reason to exclude

Constraint Engineering

Note

Constraint Engineering is a first-class concept in this methodology. It is threaded through all phases and is the primary mechanism for preventing agents from making uncontrolled changes.

Constraint Engineering is about what NOT to do — enforcing boundaries and mandating analysis before code generation. It is a proactive safety mechanism that prevents agents from going amok.

Principles

  1. Ensure analysis before generation
    • Agents must explore code via codebase-memory-mcp before writing any code.
    • Optionally, a specialist impact-analysis agent validates proposed changes before execution.
  2. Constrain agent scope
    • Explicit allow:... / deny:... lists for files, methods, interfaces, directories, and commands.
    • Agents cannot touch what they are not permitted to touch.

Conceptual Overview of Constraint Engineering

flowchart TD
    A["Agent Receives Task"] --> B["Explore via codebase-memory-mcp"]
    B --> C{"Impact Analysis Agent\n(optional)"}
    C -- Safe --> D["Apply Allow/Deny Lists"]
    C -- Unsafe --> G["Flag for Human Review"]
    D --> E{"Within Scope?"}
    E -- Yes --> F["Execute Task"]
    E -- No --> G
    F --> H["Run Quality Gates"]
    H -- Pass --> I["Submit for Review"]
    H -- Fail --> J["Revise Within Constraints"]
    J --> F
Loading

How Constraint Engineering Threads Through Phases

Phase Constraint Engineering Role
Phase 1 Establish initial allow/deny lists. Configure deterministic commands that agents must use.
Phase 3 agentic-agentDocs generates per-component constraint definitions: forbidden dependencies, data classification, ownership rules.
Phase 4 Contracts become enforceable constraints — agents must not break published interfaces.
Phase 5 Refactoring is bounded to single components. Agents cannot weaken tests.
Phase 7 Implementation plans are cross-checked against codebase-memory-mcp for impact before approval.

Assumptions

This approach is based on the following assumptions:

  1. Better context → better agent output. Context engineering is possible only with high-quality, purpose-built documentation.
  2. Model reasoning capacity is finite. Providing an LLM with unstructured information produces broken or incomplete results. The less that the LLM has to discover during runtime, the more capacity it has to understand the task and apply correct reasoning. Structured repository information can be built asynchronously and delivered synchronously. See codebase-memory-mcp.
  3. Smaller, task-specific context outperforms whole-repo context.
  4. Deterministic commands and automated quality gates reduce rework and agent uncertainty.
  5. Tests, contracts, and documentation preserve existing structure and behavior.
  6. These practices reduce common agentic coding problems: context bloat, spaghetti edits, specification drift, and inconsistent quality.
  7. Token efficiency is a byproduct, not the objective. Better context reduces wasted tokens, discarded responses, repeated analysis, and rework — while preserving code longevity.
  8. Agents significantly improve probability of correctness but do not guarantee correctness. Human review remains necessary for high-risk changes.
  9. Once documentation is built, sophisticated context engineering techniques become possible — above and beyond what is currently implemented in agentic-tdd context engineering and planned in impact analysis.

Core Intelligence Layer

codebase-memory-mcp is used by every phase to identify symbols, dependencies, callers, callees, tests, contracts, and related documentation. It serves as the shared knowledge backbone that all tools and agents query before performing work.

← Home · Legacy Phased Approach → · New Project Recipe →