Radical Geek field guide
Radical Geek's Guide to AI-Ready Codebases
A practical repository-readiness guide for authoritative context, architecture, tests, deterministic gates and bounded agentic change.
Why this guide
An AI-ready codebase gives contributors an authoritative working surface. Its structure, tests, documentation, boundaries, ownership and repeatable checks support bounded change and evidence-based acceptance.
Agents expose hidden architecture, tribal knowledge, brittle tests and undocumented build rituals very quickly. Those signals are valuable because the same gaps slow onboarding, maintenance and incident response for human engineers.
This guide turns repository readiness into a practical programme of source authority, context design, deterministic verification and evidence-ready handback.
Prepare the repository so an agent can understand the task, make a bounded change and prove the result.
What you will leave with
A guide built to be used.
- 01
Give human and agentic contributors an authoritative starting surface for real repository work.
- 02
Define source precedence, architecture boundaries, ownership and written conventions.
- 03
Build context packs and task packs around bounded work, checks, authority and handback.
- 04
Use tests, linting and CI as deterministic evidence gates for probabilistic work.
- 05
Map legacy areas, shadow context and readiness gaps into a practical improvement plan.
Inside the guide
The working ground it covers.
- What makes a codebase AI-ready
- Documentation, source authority and repository conventions
- Tests as agentic safety rails
- Architecture boundaries, code maps, ADRs and runbooks
- Context packs, task packs, search and retrieval
- CI, linting and deterministic gates
- Legacy triage and the first 30 days