This week's video

Most AI coding agent failures are not prompt problems. They are onboarding problems.

You would not drop a new engineer into a production repo with no setup instructions, no architecture map, no test commands, and no product context. But that is often how we use Codex, Claude Code, and other coding agents. We open the repo, paste in a task, and expect the agent to infer the team's conventions from code alone.

This week's video walks through what agent onboarding looks like inside a real Rails app.

Watch the video

The example is CreatorSignal, the Rails app I have been building on stream. I walk through the repo artifacts that give a coding agent usable context before it touches production code: AGENTS.md, docs/README.md, architecture notes, testing expectations, product specs, ADRs, and CLAUDE.md compatibility.

Then I give Codex a small bug fix: API key last_used_at should update at most once per minute.

The fix is intentionally small. The point is not the bug. The point is watching Codex read the right context, choose a focused test, make a narrow change, and explain the verification path.

AGENTS.md is a map, not a manual

The easy mistake is turning AGENTS.md into a giant prompt.

That is not how I think about it. AGENTS.md should be the repo entry point. It should tell the agent where to look, how to start, what commands matter, and which docs carry the source of truth for different kinds of decisions.

The useful pattern is progressive disclosure. The root file should be small enough to read every session, but specific enough to route the agent into deeper context when it needs it. Product behavior lives in product specs. System boundaries live in architecture docs. Verification expectations live in testing docs. Decision history lives in ADRs.

That gives the agent a map instead of a wall of text.

It also makes the context maintainable for humans. If the only place your conventions exist is in a long prompt, they will drift. If they live in repo-local docs that humans and agents both use, they have a much better chance of staying true.

The repo has to say what matters

The deeper issue is that agents cannot follow conventions they cannot see.

If the repo does not say how to run the app, the agent guesses. If the repo does not name the important product constraints, the agent optimizes for local code shape instead of user-facing behavior. If the repo does not describe the test strategy, the agent either runs too much, runs too little, or gives you a confident summary without meaningful verification.

That is why the video spends so much time on the surrounding artifacts before the Codex task starts.

CreatorSignal has:

• AGENTS.md as the starting point
• docs/README.md as the documentation index
• architecture docs for boundaries and repo structure
• product specs for domain behavior
• testing docs for verification expectations
• ADRs for decision history

None of those files are complicated on their own. Together, they change the shape of the coding session. Codex is no longer trying to infer the whole system from scattered source files. It has an onboarding path.

This is what I mean by agent-ready codebase design: less context trapped in your head, more context in the repo where the agent can actually use it.

The small task is the test

The bug fix in the video is deliberately modest. API key last_used_at was supposed to debounce updates, but the behavior did not match the intended one-minute window.

That kind of task is a good test of repo readiness. It is small enough that you can inspect the entire change, but real enough to touch model, spec, and verification behavior. If the agent can find the relevant product context, write or update a focused test, make the narrow fix, and explain why that verification is enough, the repo is giving it useful signal.

If it thrashes, edits unrelated files, ignores the spec, or cannot tell you what it proved, the issue may not be the model. The repo may not be onboardable yet.

That is the decision rule I would use before handing an agent larger work. Start with a small, testable task. Watch what context it reaches for. The failure mode will tell you whether you need a better prompt, a better model, or better repo-local onboarding.

If you want help doing this across a real codebase, this is the kind of work I do in a Foundation Sprint. We audit where agents lose context, tighten the repo-local onboarding layer, define the testing and review loop, and leave your team with a working AI development workflow instead of a pile of prompts.

Learn about Foundation Sprints

Stronger agents need clearer maps

Anthropic also announced Claude Fable 5 and Claude Mythos 5 this week. The software engineering claims are worth paying attention to: longer autonomous runs, stronger codebase-scale performance, and a Stripe example where Fable 5 reportedly compressed a months-long migration into a day.

They also published a Fable 5 prompting guide, and the advice points in the same direction: revisit your scaffolding, make self-verification explicit, define boundaries, and remove old instructions that are now too prescriptive. That does not make repo onboarding less important. It makes it more important. The better the model gets at long-running work, the more leverage it has to amplify whatever context, constraints, and permissions the repo gives it.

Stronger agents need clearer maps.

Read Anthropic's announcement and the Fable 5 prompting guide

Resources from the video

• CreatorSignal
• claude-code-workflows repo
• Four Dimensions of Agent-Ready Codebase Design
• Your Codebase Is the Problem, Not the AI Model
• OpenAI: Harness engineering, leveraging Codex in an agent-first world
• Anthropic: Effective context engineering for AI agents
• Anthropic: Claude Code best practices
• Agent instruction file standard

If you use coding agents in a real repo, what context do you wish the repo handed them automatically? Reply and tell me. I am especially curious about the conventions that still live in your head or in old Slack threads.

If you want a starting point, I put together a free Agent-Ready skill that helps scaffold the first layer of agent-readable repo context: get the Agent-Ready skill.

And if your team is trying to build this into its engineering practice, book an intro call. Happy to help you think through the tradeoffs.

Damian