Context Engineering for AI-Assisted Dev

Here’s something I’ve learned the hard way: how you organize your project matters more than how good your prompts are. The directory structure, the planning docs, the little markdown files that describe what things are and why — that’s the real prompt engineering. I’ve started calling it context engineering, because the work is less about crafting a clever instruction and more about curating the context that the AI tool will operate in.

The directory is the interface

When an AI coding assistant starts working on your project, the first thing it does is look around. It reads your project structure, your config files, your planning docs. That ambient context shapes everything it does.

project/
  CLAUDE.md              <-- "here's the big picture"
  planning/
    CLAUDE.md            <-- "here's how we make decisions"
    architecture.md      <-- why Iceberg over Delta, why dbt over Spark
    decisions.md         <-- the reasoning, not just the outcome
    stakeholders/        <-- who knows what, who to ask
    reference/           <-- external specs, vendor docs

A well-organized directory translates almost directly into better AI output. Not because the AI is smarter about tidy repos, but because clear organization forces you to be explicit about things you’d otherwise leave as tribal knowledge.

What actually helps

CLAUDE.md files at every level. Root for the big picture, subdirectories for specifics. These aren’t documentation for humans — they’re orientation files for the AI. Short, opinionated, current.

Decisions, not just outcomes. “We use dbt for transformations” is almost useless. “We chose dbt over Spark SQL because we need version-controlled, testable transforms that a clinical data manager could eventually review” — that lets the AI make reasonable judgment calls downstream.

Conventions as code. If you keep repeating the same instruction (“always use this AWS profile,” “review GitHub issue bodies before filing”), encode it as a skill or hook. It’s compressing institutional knowledge into something that persists across sessions.

Keeping docs honest. An outdated architecture doc is worse than none at all — it’ll confidently steer the AI the wrong direction. Updating docs has to be part of the change, not an afterthought.

The unsexy insight

If a new team member would be confused by your repo, so will the AI. The people getting the most out of AI coding tools aren’t writing the cleverest prompts. They’ve done the boring work of making their project legible. The “it just generated garbage” experience is usually a context problem, not a tool problem.