--- title: "Context Files for Product Specs, a Guide" description: "Context files give an agent the standing background a new hire gets in week one. What belongs in them, where they live, and the rule that stops them rotting." canonical_url: "https://builderscamp.com/guides/other/context-files-for-product-specs" date_published: "2026-09-18" date_modified: "2026-09-18" author: "Andre Albuquerque, Inês Lourenço" publisher: "Builders Camp" guide_class: "other" --- # How to use context files for product specs **TL;DR:** A context file gives an agent the standing background a new team member would get in week one: what the product does, who uses it, the vocabulary, and the decisions already settled. Claude Code loads these files in four scopes on every session and reads the first 200 lines or 25KB of its auto memory, which makes brevity a working constraint rather than a style preference. Write it once, prune it monthly, and never put anything in it that will be false next sprint. ## What should actually be in a context file for product work? Everything a competent new hire would be told in their first week and would then never be told again. What the product does and for whom. The words your team uses and what they mean here rather than in general. The constraints nobody relitigates: the compliance boundary, the platform you support, the customer segment you have deliberately said no to. The decisions already made and the reasoning behind them, so an agent proposes a fourth option rather than rediscovering the three you rejected. Claude Code's own documentation names that test almost exactly. Its list of what belongs in a CLAUDE.md includes anything a new teammate would need to be productive, plus two triggers that are easier to notice day to day: the agent makes the same mistake a second time, or you type the same correction you typed last session. Both mean a fact is living in your head and needs to live in a file. What that yields for product work is narrower and more useful than a general brief. Not "we value our customers," which changes nothing an agent does. Something closer to: enterprise accounts are billed annually and cannot be downgraded mid-term, so any flow that offers a plan change has to check the contract type first. ## The week one test, and why it beats writing a template Most people start a context file by finding a template and filling in its sections, which produces a document full of headings with one sentence underneath. The faster route is to write down what you would say out loud to somebody joining on Monday, in the order you would say it, and stop when you run out. Then read it back and delete anything they would have worked out on their own in a day. What survives is usually three things: vocabulary, constraints, and settled decisions. That is a good context file. It is also short, which matters more than it sounds, because these files are read on every single request and Anthropic's own guidance on context engineering frames the job as curating and maintaining the smallest useful set of tokens at inference time rather than loading everything available. The failure mode on the other side is real too. A file with no constraints in it produces an agent that writes plausible specs for a product that does not exist. ## Where the files live, and why the layering is worth understanding Claude Code loads context in four scopes, from broadest to most specific: a managed policy file an organisation can deploy to every user, a user-level file at `~/.claude/CLAUDE.md` for your own preferences across all projects, a project file at `./CLAUDE.md` or `./.claude/CLAUDE.md` that your team shares through source control, and a personal `./CLAUDE.local.md` you keep out of version control for things only you need. Project instructions load after user instructions, so the more specific scope has the last word. For spec work, almost everything belongs in the project file, because product facts are facts about the product rather than about the person writing. The user file is for how you like documents written; the project file is for what is true. Mixing them is how a personal preference about heading style ends up quietly governing how a whole team's specs get drafted. Two mechanisms sit alongside this and are worth knowing rather than using immediately. `.claude/rules/` holds topic-specific or path-scoped rules for larger projects, which keeps the main file from growing to hold every situational instruction. And auto memory, where the agent writes its own notes from your corrections, loads the first 200 lines or 25KB of that file into each session, a cap that exists precisely because unbounded accumulated context stops helping. ## What does not belong in a context file Anything with a shelf life shorter than a quarter. Sprint numbers, current ticket status, this month's priorities, who is covering what. These read as useful context and become wrong within weeks, at which point the agent is confidently working from a stale premise and nothing in the file says so. Also worth keeping out: secrets of any kind, since the file is read in every session and usually committed; long background documents that would be better retrieved when relevant than loaded always; and anything phrased as an aspiration. "We prioritise accessibility" changes nothing. "Every new screen needs keyboard navigation and visible focus states, and a spec without them is not ready for review" is a constraint an agent can act on. One more, less obvious: enforcement. Claude Code's documentation is direct that these files are treated as context rather than enforced configuration, and that blocking an action regardless of what the agent decides requires a hook. A sentence in a markdown file saying "never do X" is a strong hint, not a guarantee, and writing it in capitals does not change that. ## How context files rot, and the rule that stops it They rot in one specific way: by accumulating. Somebody adds a line during a frustrating session, nobody deletes it, and eighteen months later the file contains a rule referring to a system that no longer exists. The agent follows it, because it has no way of knowing which lines are current. The maintenance rule worth adopting is a deletion quota, not an addition process. Once a month, open the file and delete something. If nothing is stale, the file is healthy and you have spent four minutes confirming it. The habit matters more than the interval, because the alternative is that the file only ever grows, and a growing context file degrades in quality even as it looks more thorough. [Context architecture](https://builderscamp.com/guides/glossary/context-architecture) covers the wider discipline this sits inside, and [agent memory](https://builderscamp.com/guides/glossary/agent-memory) covers what persists between sessions rather than within one. ## What changes when the output is a spec rather than code Code carries some of its own context. An agent reading a repository can infer naming conventions, the testing framework, and how errors are usually handled, without being told. A product decision has no such trace. The reason you killed the self-serve enterprise flow in 2024 exists in a meeting nobody recorded, and an agent drafting a spec will cheerfully propose it again. This is the gap Builders Camp's Building your AI Operating System bootcamp is built around: it opens with context layer design, structuring a markdown-based context system so agents can execute product work reliably, before moving to reusable skills for PRD generation and research synthesis. Its practical challenge asks you to build one slice end to end, a recurring workflow, the context an agent needs to do it well, the skill that runs it, and an honest check on whether the output is repeatable across runs. Builders Camp's Building with Claude Code covers the same layer from the engineering side, alongside multi-agent orchestration and quality gates, and both sit inside the AI Agentic Builders Expert Track. ## Who this is for, and who it is not for This fits a product manager who has started drafting specs with an agent and keeps re-explaining the same four things. It is a poor fit if you are still deciding whether to use an agent at all: writing context files before you have a workflow to attach them to produces a tidy document nobody reads. Start by doing the work manually twice, notice what you retype, and write that down. ## Write the file for the version of you who has forgotten The best line in a context file is usually one that felt too obvious to write. Six months out, you will not remember why enterprise accounts are exempt from the trial flow, and neither will the agent. Try this the next time you finish a spec: before closing the document, write down the one fact you had to hold in your head the whole time you were drafting it, and put that line in the file. Do that ten times and you have a context file nobody had to sit down and author. [See the Building your AI Operating System bootcamp](https://builderscamp.com/bootcamps/building-your-ai-operating-system?utm_source=guide&utm_medium=organic&utm_campaign=context-files-for-product-specs) For the hard limit all of this works inside, see [context window](https://builderscamp.com/guides/glossary/context-window). For the wider system these files are one layer of, see the [AI operating system](https://builderscamp.com/guides/glossary/ai-operating-system) and the [AI Agentic Builders Expert Track](https://builderscamp.com/tracks/ai-agentic-builders-expert). ## Frequently asked questions ### What is a context file, in practical terms? A plain markdown file an agent reads at the start of every session, holding facts that are always true about your product: what it does, who uses it, what the words in your domain mean, what you have already decided, and what nobody is allowed to change. Claude Code's own documentation calls these CLAUDE.md files and loads them into every session. ### How is a context file different from a prompt? A prompt is the request for this task. A context file is the standing background every task assumes. The test is repetition: anything you have now typed into a chat twice belongs in the file, and Claude Code's documentation names that exact trigger, alongside the agent repeating a mistake you already corrected. ### How long should a context file be? Short enough to stay true. Claude Code's auto memory reads the first 200 lines or 25KB of its memory file, and the documentation states plainly that more specific and concise instructions are followed more consistently. A long file is not a richer file; it is a file with more stale lines in it. ### Where do context files actually live? Claude Code loads them in four scopes, broadest first: an organisation-managed policy file, a user file at ~/.claude/CLAUDE.md, a project file at ./CLAUDE.md or ./.claude/CLAUDE.md, and a personal ./CLAUDE.local.md you keep out of version control. Product context belongs in the project file, since it is a fact about the product rather than about you. ### Does a context file guarantee the agent follows it? No, and the documentation is explicit about this: these files are treated as context, not enforced configuration. To block an action regardless of what the agent decides, you need a hook, not a stronger sentence in a markdown file. ### What should never go in a context file? Anything that is true this week and not next: sprint numbers, the current status of a ticket, who is on holiday. Also anything secret. A context file is read in every session and usually committed to the repository, so treat it as public to your whole team. ### Do context files help when the output is a spec rather than code? More, if anything. Code is partly self-documenting, so an agent can infer conventions by reading it. A product decision made in a meeting eighteen months ago leaves no trace anywhere an agent can read, which makes writing it down the only way it survives. ## Sources - [Claude Code Docs: How Claude remembers your project (CLAUDE.md and auto memory)](https://docs.claude.com/en/docs/claude-code/memory) - [Anthropic: Effective context engineering for AI agents](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents) ## How this guide was made Researched from Builders Camp's bootcamp, track and masterclass material and the sources listed on this page, drafted with AI, and fact-checked against every source cited.