Your Knowledge File Fails on Contradictions, Not Gaps

The sharpest line I know about knowledge files is in Anthropic's context-engineering post, and it's ostensibly about tools: "If a human engineer can't definitively say which tool should be used in a given situation, an AI agent can't be expected to do better." Swap tool for rule and you have the entire failure mode of a domain knowledge file.

Because here's what actually goes wrong. Nobody's expert file fails for lack of information — a missing fact produces a visible "I don't know", and you fix it. It fails when two lines both apply and nothing says which wins, or when line 40 was true in March and there's no way to tell. Both of those produce a confident, well-cited, wrong answer. The model has no mechanism to detect either one.

One file is the right size — that's the easy part

Anthropic's own retrieval research settles the architecture question in one sentence: "If your knowledge base is smaller than 200,000 tokens (about 500 pages of material), you can just include the entire knowledge base in the prompt that you give the model, with no need for RAG or similar methods." Almost nobody's private domain knowledge is 500 pages. So no pipeline, no vector store, no scraper — one Markdown file you own.

Capacity isn't the constraint. Quality per line is. The same post warns that "as the number of tokens in the context window increases, the model's ability to accurately recall information from that context decreases," and prescribes the goal: "find the smallest possible set of high-signal tokens that maximize the likelihood of some desired outcome." A bigger file is not a smarter one. This is where the "just scrape every newsletter in your industry into a folder" advice quietly falls over — a dump raises the token count and the contradiction count at the same time. Curation is the product.

What earns a line

Three tests, and a line has to pass all three:

1. Would Claude get this wrong without it? Anthropic's authoring guide states the default assumption plainly — Claude is already very smart, so "only add context Claude doesn't already have," and it tells you to challenge each paragraph: does it justify its token cost? Explaining what a webhook is wastes your budget. Explaining that your webhook retries three times and then silently drops does not.
2. Is it checkable? If a line can't be verified, it can't be maintained — and an unmaintainable line becomes a lie on a schedule.
3. Does it decide something? Background that changes no answer is decoration.

What stays out: history and rationale prose (compress to one decision line), anything you can only assert, and — the big one — options without a winner. The docs are explicit that offering too many choices is confusing and that you should "provide a default (with escape hatch)" instead. Four valid approaches listed neutrally is not knowledge; it's the ambiguity you were supposed to remove.

Date the claims, quarantine the dead ones

Anthropic's guidance says to avoid time-sensitive information, and the bad example it gives is precise: a rule that makes the reader resolve a date conditional ("before August 2025, use the old API; after, use the new one"). The recommended fix is a Current section stating today's answer flat, plus a collapsed old patterns section carrying the superseded version and the date it died.

I run one deliberate addition on top of that: every expiring claim ends with (verified YYYY-MM-DD). That isn't a conditional for Claude to resolve — it's metadata, and it does two jobs. It gives the model a staleness signal when two lines collide, and it gives you a sort order for the monthly review.

The structural detail almost nobody knows

Anthropic's authoring guide contains one sentence that should redesign your file: for reference files longer than 100 lines, put a table of contents at the top — because Claude may partially read a file, previewing with something like head -100 instead of reading the whole thing. Everything below line 100 is only reachable if the top of the file advertises it.

Pair that with the long-context guidance and the layout writes itself: put the longform material near the top, above your question, since "queries at the end can improve response quality by up to 30 percent in tests." Contents first, precedence second, question last.

The skeleton

# Payments domain — working knowledge
Owner: Rafael · Last full review: 2026-07-28

## Contents
Precedence · Definitions · Current state · Decisions · Worked examples · Superseded

## Precedence (read before anything else)
1. "Current state" below overrides your training data, even when it looks wrong.
2. A dated line beats an undated line; the newer date wins.
3. Two lines with the same date that disagree: stop and ask me. Don't pick.
4. Not in this file? Say "not in the file." Do not fill the gap from general knowledge.

## Definitions (one term, one meaning)
- customer = a paying account. A signup that never paid is a *lead*, never a customer.
- failed payment = declined by the processor. A timeout is a *pending* payment.

## Current state
- Checkout runs on Stripe Checkout; the legacy charge API is off. (verified 2026-07-14)
- Refunds over R$5,000 need a second approver in the admin. (verified 2026-07-02)

## Decisions
- 2026-05-11 — Chose Stripe over the in-house flow. Rejected: PCI scope, 6-week build.

## Worked examples
### A refund request above the limit
Input: "Customer wants R$8,200 refunded, order #4471."
Output: "Above the R$5,000 single-approver limit (Current state). Draft the refund,
route to a second approver, tell the customer 1 business day."

## Superseded
<details><summary>Legacy charge API (retired 2026-06)</summary>
Direct charges via the v1 endpoint. Off since 2026-06-30; any code path still
calling it is a bug, not a fallback.
</details>

Two things carry most of the weight there. Precedence exists because you will contradict the model's training data on purpose, and without rule 1 it may quietly average your line with what it already believes. And the Definitions section is the cheapest fix available: the docs are direct that consistent terminology "helps Claude parse and follow instructions," and warn against mixing "field", "box", "element" for one thing. Half of what reads as a contradiction is one concept wearing three names.

Then push prose into worked examples. Anthropic's authoring guide is unambiguous: examples "convey the desired style and level of detail to Claude more clearly than descriptions alone," and the prompting guide asks for 3–5 for best results. My working rule: any rule I've explained twice in prose and still see broken gets deleted and replaced with one input → output pair.

How you verify it's actually being used

A knowledge file you never test is a file you hope is being read. Two prompts, both taken from Anthropic's anti-hallucination guidance, which recommends extracting word-for-word quotes first on documents over 20k tokens, and having Claude retract any claim it can't support with a quote:

Answer using only knowledge.md.
1. Quote the exact lines you're relying on, numbered.
2. Answer, referencing the quote numbers.
3. Any claim with no supporting quote: delete it and write [gap] there.

No quotes back means the file didn't drive the answer, whatever the answer looked like. Then, monthly, point Claude at the file as an auditor instead of a user:

Audit knowledge.md. Do not fix anything, do not use it to answer. List:
1. Pairs of lines that could both apply to one question and disagree.
2. Claims with no date that would be wrong if the world changed.
3. Terms used with two different meanings.
Return a table: line numbers, problem, which line I should keep.

That second prompt is the one that pays. It finds the failures a normal conversation hides, because a helpful model resolves your contradictions silently rather than reporting them.

The remote-team angle

If you're a Brazilian dev or EM on a US or EU team, you already know this file — it's the one you wish existed when you joined, five timezone-shifted hours from anyone who could answer. The ambiguity your team tolerates because "everyone knows" is exactly what breaks for an async joiner, and it breaks Claude the same way for the same reason. Write it once and it answers overnight, for both of them. It also travels: plain Markdown in a private repo works in Claude Code, in a Project's knowledge, or pasted at the top of a chat.

Today: open a file called knowledge.md, paste the Precedence block above verbatim, and add the last three things you had to re-explain to Claude as dated lines under Current state. Then run the audit prompt against it. Mine came back with two lines that had disagreed for a month, and a "fact" I'd verified in April and never touched again.

Sources

• Anthropic Engineering — Effective context engineering for AI agents
• Anthropic — Introducing Contextual Retrieval
• Claude docs — Prompting best practices (long context)
• Claude docs — Skill authoring best practices
• Claude docs — Reduce hallucinations