Great Idea!
That's the response I'm most suspicious of when I get it from an AI. It arrives with the same enthusiasm whether the idea is good, half-baked, or obviously broken.
I've shared half-baked proposals, underspecified designs, and code with obvious gaps and watched the agent validate all of them. "Great idea, here's how to extend it." "This looks solid — a few things to consider." The enthusiasm is consistent. The critical distance is not.
LLMs are trained on human feedback, and humans tend to rate encouraging responses higher than critical ones. The model learns to agree. For conversational use, that's mostly fine. For serious work — anything where the point is catching what you missed — it's a liability.
You don't fix this by prompting differently each session. You fix it once, at the project level. That fix is a file.
The Instruction File
Every serious AI coding tool supports some version of a project-level configuration file: a document placed at the root of your project that the agent reads before doing anything. Claude Code uses CLAUDE.md. Other tools use AGENTS.md, or their own equivalent. The names are fragmented; the concept is identical.
Practical advice: use the filename your primary tool expects. If you're on Claude Code or Cowork, that's CLAUDE.md. If you're working across multiple tools and Claude isn't one of them, AGENTS.md has the broadest cross-tool support.
A note for readers using legal-specific AI platforms rather than general-purpose agents: if your tool doesn't support any version of this — no project-level instruction file, no configurable system behavior, no way to tell it what it's working on before the session starts — the tool has already decided how it works for you.
Map, Not Manual
Most people who discover instruction files write walls of text. I did too at first. A long list of conventions, explanations, edge cases, historical context — everything the agent might conceivably need, dumped into one file.
This is the wrong model. Context windows are finite, and everything the agent loads upfront is context it can't use for your actual work. An instruction file that reads like a policy manual is expensive and usually ignored in practice — agents skim long files the same way humans do.
Think about a one-page brief you'd hand a new colleague on their first day. Not the case files. Not the full practice guide. One page: what this project is, where things live, what we care about, what the non-negotiables are. That's the instruction file.
A good one has four things: a short project description that tells the agent what it's working on, a behavioral config that says how you want it to engage, a handful of non-negotiable rules, and an index pointing to the docs/ folder where everything else lives. Anything that needs more than a line or two belongs in its own doc.
The behavioral config is where you resolve the sycophancy problem from the intro. Instead of prompting for pushback each session, you set it once:
## Your Role
You are a sparring partner, not an assistant. Challenge my assumptions.
Tell me when an idea is weak or when I'm going off track. Don't agree
to be polite — if something is wrong or half-baked, say so and explain why.
The final decision always rests with me. Your job is to make sure I've
considered the tradeoffs before I make it.
Now that behavior is the default for every session in that project. You don't re-litigate it.
The other three components handle context: what the project is, what the rules are, where to find everything. Here's what all four look like together in an example Python document pipeline project:
# Due Diligence Document Pipeline
> Python pipeline for extracting, classifying, and structuring documents from M&A
> deal rooms into a searchable database for deal team analysis.
---
## Core Rules
_These always apply. Full conventions in [docs/conventions.md](docs/conventions.md)._
- Package management: `uv` only. Never `pip install` directly.
- Credentials and API keys in `.env` always — never hardcoded, never committed.
- All deal documents are strictly confidential — never log content, never include in examples.
- Type annotations required on all function signatures.
- LLM model and provider configurable via environment variables, not hardcoded.
- Ask before making significant design choices or changing extraction schemas.
- Commit per task group (conventional commits: `feat:`, `fix:`, `chore:`).
---
## Project Map
| Document | Purpose |
|---|---|
| [docs/mission.md](docs/mission.md) | Goals, document types in scope, success criteria |
| [docs/tech-stack.md](docs/tech-stack.md) | Python, LLM provider, vector store, orchestration decisions |
| [docs/roadmap.md](docs/roadmap.md) | Pipeline phases and status |
| [docs/conventions.md](docs/conventions.md) | Full coding standards, schema conventions, output formats |
| [docs/glossary.md](docs/glossary.md) | Deal room terminology — read before planning |
| [docs/decisions/](docs/decisions/) | Key architectural choices (chunking strategy, model selection, etc.) |
| [specs/](specs/) | Feature specs (YYYYMMDD-feature-name/) |
| [bugfix.md](bugfix.md) | Open issues |
| [TODO.md](TODO.md) | Ideas and deferred items |
| [CHANGELOG.md](CHANGELOG.md) | Shipped pipeline stages and findings |
---
## Current Focus
Phase 2: Structured extraction — pulling deal terms and party names from NDA and LOI documents.
See [docs/roadmap.md](docs/roadmap.md).
---
## Quick Start
```bash
uv sync
cp .env.example .env # fill in LLM API keys and DB connection
uv run python pipeline/ingest.py --source data/raw/
If you are asking yourself what kind of weird syntax that is – it's markdown. I covered the importance of being familiar with this file format in my first blog post – you should be already familiar with it ;-)
What's doing the work here is what's not in the file. There's no explanation of what the chunking strategy is — that's in docs/decisions/. There's no logging pattern, no test structure, no schema definitions — those are in conventions.md. The instruction file points; the docs contain.
The example above is a starting point, not something to copy wholesale. The specific folder names are secondary. What matters is the thinking behind them: how do you structure a project — coding, legal or otherwise — so that the artifacts it produces are stored in a predictable place, so that the agent can navigate it without being walked through it each session, and so that the structure still holds when the project is ten times larger than it is today? That question is worth spending real time on. A project that has a clear, consistent structure from the start is one where the agent stays useful as complexity grows. One that doesn't will slowly drift toward sessions where you spend more time re-orienting the agent than doing the actual work.
The Docs Layer
The docs/ folder is where the real project knowledge lives. Each file answers one question in enough depth to actually be useful: what are we building and why (mission.md), how does the work flow end-to-end and what's the tech stack (tech-stack.md), what are the accepted output formats and conventions (conventions.md), what decisions have been made and why (decisions/).
The agent reads the instruction file on every session. It pulls from docs/ only when a task requires it — when conventions matter for a specific output, when a past architectural decision is relevant to the current task, when the glossary is needed to avoid misaligned terminology. Progressive disclosure: load the general orientation once, load the specifics when they're needed.
The structure I use for docs/ is consistent across every project. The contents differ completely — a document pipeline and a browser extension look nothing alike in there — but the folder names and what each file is for stay the same. That consistency pays off when you're orienting a new session quickly, or when a skill needs to navigate the project structure without being told where things are.
If the project map above looks like a lot of files to create, most of them start as placeholders and fill in as the project moves forward. A decision record gets written when a decision is made. The glossary grows as domain terms come up. The mission doc gets written once and rarely changes. Conventions are the exception — those transfer across projects. The coding standards and preferences I've built up over time show up in every new project; they don't change often, but they expand whenever I settle on a new pattern. You can draft all of these with the LLM itself — a short conversation about the project produces a solid first version of mission.md, and a conversation about how you like to work produces most of conventions.md. Better still, you can build dedicated skills for each of these moments: a skill that runs a structured interview to write the mission doc, one that updates conventions after a refactor, one that logs a decision in the right format. That's how the docs layer stays current without becoming a maintenance burden.
This connects directly to skills, which I covered in the previous post. The instruction file is always-on — it's read at the start of every session and sets the permanent context and behavior for that project. A skill is triggered on demand — loaded when you need a specific workflow to run. The instruction file is the standing brief. The skill is the task instruction. They operate at different levels but they should be tightly integrated.
Start Small, Update Often
The worst approach is trying to write the perfect instruction file before you've done any real work in the project. You don't know yet what context the agent will need, what behavior will drift, what edge cases will matter. A file you write speculatively will miss half of it and get the other half slightly wrong.
Start with two things: the behavioral config shown above and a one-paragraph description of what the project is. That's enough. It takes ten minutes and immediately changes how the agent engages.
Then pay attention. When you find yourself re-explaining the same context across sessions, that context belongs in a doc. When the agent goes off-track in a specific, repeatable way — assumes the wrong stack, uses a format you don't want, skips a step it should always take — that's the instruction file telling you something is missing. Add it.
The structure I use now evolved across several projects. Each revision was small. Each came directly from a session where something didn't work and I understood why. The file got better because the project did, not because I planned it well upfront.
Once you have a structure that works across projects, build a skill that stamps the whole thing out — instruction file, docs/ scaffold, folder structure — in a single command. That's how you stop reinventing setup and start every project from your current best understanding of how to run one.