# Agent First Codebase > Diagnose and transform a codebase so coding agents (Claude Code, Codex, and similar) can work in it reliably and autonomously. Based on the practices OpenAI's Codex team used to ship a 1M-line internal product with zero human-written code. Use this skill whenever the user wants to set up or restructure AGENTS.md / CLAUDE.md, organize a docs/ directory for AI agents, diagnose why Claude Code keeps making mistakes in their repo, make their codebase "AI-friendly" or "agent-first", references "harness engineering" or Codex best practices, audits an existing repo's agent-readability, or is starting a new repo they plan to develop heavily with AI assistance. Also trigger if the user complains that their agent "forgets context", "reinvents patterns", or "ignores conventions" — those are symptoms this skill addresses at the structural level. - Skill: `soulfaro/agent-first-codebase` (Agent Skill, multi-file: 27 files) - Install (CLI): `npx skillmds@latest add soulfaro/agent-first-codebase` - Raw SKILL.md: https://api.skillmd.com/api/skills/soulfaro/agent-first-codebase/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - License: MIT - Author: SoulFaro (https://skillmd.com/u/soulfaro) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/soulfaro/agent-first-codebase --- # Agent-First Codebase Transform a codebase into one where coding agents can reason and work reliably. Based on the practices OpenAI's Codex team used to ship a 1M-line internal product with zero human-written code. ## Core premise Agents can only reason about what's in their runtime context. Knowledge in Slack, Google Docs, issue trackers, or teammates' heads does not exist to them. A 2,000-line AGENTS.md full of rules doesn't help either — it crowds out the actual task. The goal of this skill is to push the project's real state into the repo as **structured, navigable, machine-checkable artifacts**, so agents can act without a human in the loop. Five patterns underpin everything here. Understand them before proposing changes; they are the "why" behind every recommendation. 1. **Map, not encyclopedia** — A short AGENTS.md (~100 lines) that points to structured docs/, not a giant dump of rules. 2. **Progressive disclosure** — Small stable entry point; agent navigates deeper when needed. 3. **Enforced invariants** — Linters and structure tests block drift. Docs that say "please do X" drift; code that says "cannot do X" does not. 4. **Agent-readable signals** — Logs, metrics, UI state, and error messages must be queryable from within the agent's runtime. Errors should embed the fix. 5. **Golden principles + garbage collection** — A background loop (often a periodic agent task) that detects drift and files cleanup PRs. If the user pushes back on a recommendation, open `references/philosophy.md` — it has the deeper rationale. ## Workflow Phases go in order. **Get user confirmation between phase 2 (diagnosis) and phase 3 (execution).** Do not scaffold files until the user agrees on what's missing — scaffolding the wrong thing is worse than scaffolding nothing. ### Phase 1: Orient Understand the starting state. The user is usually in one of three situations: - **Greenfield** — new or near-empty repo, wants the right structure from day one. - **Existing repo, no agent scaffolding** — has code, no AGENTS.md or CLAUDE.md, wants to add. - **Existing repo, some scaffolding** — already has AGENTS.md/CLAUDE.md but agents still struggle; wants an audit. If unclear, ask. Also ask (briefly — one message): - Language/stack and monorepo layout? - Solo project, team project, or agent-heavy? - Have they had specific pain points with Claude Code / Codex in this repo? The last one is gold — recurring agent failure modes are the best signal of what scaffolding is missing. ### Phase 2: Diagnose Run through `references/diagnostic-checklist.md`. At a minimum: 1. **Top-level files** — Read AGENTS.md, CLAUDE.md, README.md if present. Count lines. Flag AGENTS.md/CLAUDE.md if >200 lines (likely encyclopedia-style). 2. **docs/ structure** — Check for subdirs: `design-docs/`, `exec-plans/`, `product-specs/`, `references/`. Flag missing ones. 3. **Architecture doc** — ARCHITECTURE.md or equivalent. Flag if missing or clearly out of sync with code. 4. **Enforcement** — Grep for custom lints, structure tests, CI jobs that run them. Agents honor what's enforced, ignore what's merely documented. 5. **Error legibility** — Skim a few lint/test error messages. Do they tell the agent how to fix the problem, or just what's wrong? 6. **Recent agent failures** — If user mentioned pain points, or if there are agent-authored PRs to browse, look for recurring failure modes. Those are the real gaps. Produce a report with this shape: ``` # Agent-Readability Diagnosis ## Current state - AGENTS.md / CLAUDE.md: - docs/ structure: - Architecture doc: - Enforcement: - Error legibility: ## Gaps (prioritized) 1. [HIGH] — 2. [MED] — 3. [LOW] — ## Proposed changes - Create : - Restructure : - Add : - Defer: ``` **Prioritize ruthlessly.** A solo side project doesn't need the full apparatus. A 10-person team building production software benefits from all of it. Match scope to the actual situation — call out explicitly when you're deferring something because it's overkill for their scale. Share the report. Wait for user confirmation before writing files. ### Phase 3: Execute Only after the user approves. Use templates in `assets/`: - `assets/AGENTS.md.template` — root-level map file (~100 lines, pointers only) - `assets/ARCHITECTURE.md.template` — top-level domain/layer boundaries - `assets/exec-plan.md.template` — workstream plan with decision log - `assets/docs-layout.md` — reference for docs/ subdirectory layout When filling templates, **leave placeholders for project specifics you don't know**. Don't hallucinate team names, service boundaries, or product decisions. Write `` with a short hint about what belongs there. For directory scaffolding, create the shells: - `docs/design-docs/index.md` (one line: "Index of design documents") - `docs/exec-plans/active/` and `docs/exec-plans/completed/` (empty, with README explaining the split) - `docs/product-specs/index.md` - `docs/references/` (for vendored LLM-friendly reference docs like `nixpacks-llms.txt`) Do **not** generate fake design docs, product specs, or exec plans — those capture real decisions and must come from real work. Scaffold the slots, not the contents. For layered architecture and lint-as-guidance: consult `references/layered-architecture.md`. Recommend selectively. On a small repo, suggest it as a future direction rather than imposing it now. For golden principles + doc-gardening loop: see `references/golden-principles.md`. Suggest 3–5 starter principles tailored to what you saw in the diagnostic, plus a doc-gardening prompt the user can run periodically (manually, via cron, or via a scheduled agent). After executing, summarize what was created, what was left as TODOs for the user, and what was deferred. ## Things to avoid - **Don't over-scaffold.** If the user's AGENTS.md is already map-style and under 150 lines, leave it alone. Praise what's working. - **Don't impose a stack.** This pattern is language- and framework-agnostic. Templates use neutral placeholders. - **Don't replace what exists blindly.** If CLAUDE.md and AGENTS.md both exist, check the contents before merging — some setups route different agents to different files. Ask. - **Don't write code for the user.** This skill scaffolds structure. Implementing actual linters, CI jobs, and domain code is the user's (or a future agent run's) job — but do provide concrete example snippets they can adapt. - **Don't pad the AGENTS.md.** The biggest trap is treating it as a list of every rule you can think of. Every line costs context. Write only what an agent would need on a cold start. ## Reference files Read when relevant — keep them out of context otherwise. - `references/philosophy.md` — The "why" behind each pattern. Read if the user pushes back or asks for rationale. - `references/diagnostic-checklist.md` — Full diagnostic heuristics with scoring criteria. - `references/layered-architecture.md` — The strict domain-layered architecture pattern and how to enforce it. - `references/golden-principles.md` — Durable rules, error-as-fix-instruction, and the doc-gardening loop. ## Assets - `assets/AGENTS.md.template` — root map file - `assets/ARCHITECTURE.md.template` — architecture/layering doc - `assets/exec-plan.md.template` — workstream plan template - `assets/docs-layout.md` — docs/ subdirectory layout reference