Teaching an AI to Understand a Codebase (Without Endless Prompting)

5 minute read

How a documentation scaffold transformed AI-assisted development from frustrating re-prompting to genuine productivity. Less slop, better design.

// experimental: AI tooling evolves weekly. Treat this as a starting point, not gospel.

Everyone’s using AI coding assistants now. Claude, Copilot, Cursor - take your pick. Most developers get mediocre results.

The default experience goes something like this: you paste in some code, ask for a feature, and get back something that technically works. It compiles. The tests pass. But it doesn’t fit. The patterns are wrong. The naming is off. It’s solving a problem you didn’t quite have, in a style that doesn’t match your codebase.

So you re-prompt. Explain the context again.

> Actually, we use repositories here, not direct Eloquent calls.
> Actually, this needs to work with our tenant scoping.
> Actually, read the existing code first.

Rinse, repeat, for every session.

I was building an enterprise Laravel application - the kind where architectural consistency isn’t optional. Multi-tenancy, complex domain logic, hundreds of tests to maintain. The “just use AI” approach wasn’t going to cut it. Every AI-generated suggestion that ignored our patterns was technical debt waiting to happen.

I needed something better than prompting my way through every session. So I built a tool to generate it for me.

What if the AI could onboard itself?

Here’s the thing about Claude: it’s brilliant, but amnesiac. Every conversation starts from zero. No memory of your architecture decisions. No knowledge of your naming conventions. No idea that you spent three weeks getting tenant isolation right and you’d rather not have it casually broken.

The realisation hit me mid-project: what if I treated AI like a senior developer joining the team?

When a human joins, you don’t expect them to intuit your codebase. You give them documentation. Architecture diagrams. A glossary of domain terms. You explain the critical rules - the things that will break production if they get them wrong.

Why wasn’t I doing this for AI?

So I started writing:

/CLAUDE.md        # critical rules, code patterns, glossary
/PROGRESS.md      # what's built, what's blocked, what's next
/docs/features/   # specs for each feature
/docs/decisions/  # architecture decision records

The works.

Then the meta-problem appeared: I was going to need this for every project. And writing 14 interconnected documentation files from scratch each time wasn’t realistic.

The solution was a scaffold - a template that generates all of this from a simple project brief. I called it PROJECT_SCAFFOLD.

What PROJECT_SCAFFOLD actually does

The scaffold is a single markdown file. You fill in Part 1 - your tech stack, constraints, domain context, first milestone, and a glossary of terms. Then you run one command:

cat PROJECT_SCAFFOLD.md | claude -p

Claude reads your brief and generates a complete documentation structure. Not boilerplate. Actual, contextual documentation based on what you told it.

Out comes a complete project structure:

├── CLAUDE.md                    # master context file
├── PROGRESS.md                  # living project tracker
├── .claude/
│   └── skills/                  # reusable task patterns
└── docs/
    ├── spec/                    # data models, multi-tenancy rules
    ├── features/                # user stories, edge cases
    ├── decisions/               # architecture decision records
    ├── conventions/             # testing, security checklists
    └── troubleshooting.md       # the mistakes you're about to make

The clever bit is platform-specific intelligence. Tell the scaffold you’re building a Shopify app, and it injects webhook HMAC verification patterns, Billing API state machine documentation, and GDPR compliance checklists. Laravel SaaS? Multi-tenancy scope leakage warnings, queue job tenant context rules, foreign key validation patterns.

The AI now understands your project before writing a single line of code.

Less slop, better design

The result was immediate. Code suggestions started following existing patterns instead of inventing new ones. The “technically correct but architecturally wrong” suggestions dropped off.

When Claude knows your Stock model uses a BelongsToTenant trait, it stops suggesting raw Eloquent queries that bypass tenant scoping. When it knows your API uses form request validation with specific FK rules, it generates code that matches.

The scaffold enforces consistency in ways that prompting can’t. A glossary means Claude uses the right terms:

# Without scaffold
"User", "Merchant", "Account", "Client"  # depending on mood

# With scaffold
"Dealer"  # every time, because it's in the glossary

Critical rules with code examples mean the same patterns appear everywhere.

Quality went up. Re-prompting went down. The cognitive load of reviewing AI suggestions dropped because I wasn’t constantly catching architectural violations.

This isn’t magic. It’s preparation. The AI was always capable of this - it just needed the context to do it well.

This is just the start

I’m not claiming the scaffold is finished. It’s a snapshot of what’s working now, on this project, with current AI capabilities.

As models get better at maintaining context across sessions, some of this may become unnecessary. As AI agents become more autonomous, the documentation patterns will evolve. The scaffold that works for a 15-phase enterprise Laravel build might be overkill for a weekend side project.

The principle, though, won’t change: preparation beats prompting.

You can fight the same battles every session, re-explaining your architecture and catching the same mistakes. Or you can invest upfront in teaching the AI how your project works.

The scaffold is one approach. There will be others. The point is that “just use AI” isn’t a strategy - it’s an abdication of one. Treating AI as infrastructure, not magic, changes how you work with it.

The cheeky truth

Here’s the part I didn’t expect: I now write better documentation for Claude than I ever wrote for human colleagues.

Every critical rule has a code example. Every architectural decision has a rationale. Every domain term has a definition. The kind of documentation I always meant to write but never quite got around to.

Maybe that says something about AI - that it forces a level of explicitness that humans muddle through without. Maybe it says something about me - that I needed a machine to make documentation feel worth the effort.

Either way, I’ll take it. The codebase is cleaner, the AI is useful, and I’ve accidentally become the kind of developer who writes things down.

The machine is finally earning its keep. And apparently, so am I.

The scaffold is on GitHub if you want to see how it works.

If you’re experimenting with AI-assisted development, I’ve written more about prompt engineering best practices and AI code generation in my AI series. For autonomous overnight loops, see Ralph Loop Gotchas - the hard-won lessons from running AI refactors while you sleep.