AGENTS.md and CLAUDE.md for a knowledge base

AGENTS.md and CLAUDE.md are plain markdown files that coding agents read before they work in a folder. In a knowledge base, they are where you tell agents how your notes are organised and which rules every document must follow. Neither file has required fields or a schema: you write instructions in ordinary markdown.

This guide covers the manual setup first. Next to each part, you'll see what changes with Knowtarium, our desktop app for knowledge bases that people and agents write together, and the skill it includes.

AGENTS.md

AGENTS.md is an open format for guiding coding agents, stewarded by the Agentic AI Foundation under the Linux Foundation. Many coding agents read it, including OpenAI Codex and Cursor. You put it at the root of your folder, and you can add more in subfolders: the nearest AGENTS.md to the file being edited wins, and what you type in the chat overrides all of them.

CLAUDE.md

CLAUDE.md is Claude Code's version. According to Anthropic's docs, Claude Code reads it from several places, broadest first:

Organisations can also deploy a managed CLAUDE.md. Files don't override each other: Claude Code concatenates them, from the filesystem root down to where you started it, so the most specific instructions come last. Files in subfolders load when Claude reads a file in that subfolder. A CLAUDE.md can pull in other files with @path/to/file, up to four levels deep. Anthropic recommends keeping each file under 200 lines.

If you use more than one agent, write your rules once in AGENTS.md. Recent versions of Claude Code read AGENTS.md on their own when there's no CLAUDE.md or CLAUDE.local.md in the folder or above it (v2.1.277 and later). If you also want Claude-specific instructions, or you're on an older version, create a CLAUDE.md next to it that imports it:

@AGENTS.md
 
## Claude Code
 
- Work in plan mode for any change that touches more than three documents.

Claude reads the imported AGENTS.md first, then the lines below it. Every other agent reads AGENTS.md directly, so the rules never drift apart.

Most AGENTS.md examples are written for code: build commands, tests, style. A knowledge base needs different rules. These are the ones that matter most when agents write a lot of your notes.

Folder layout

Say what each top-level folder is for and where new documents go. Without this, agents invent folders, and two agents file the same kind of note in two places.

Naming

One concept per file, one naming pattern. Dated names for decisions and meetings make the folder sort itself.

Linking

Pick one link style and say so. Standard markdown links work in every tool; [[wikilinks]] only work in some. Tell agents to update links when they move a file, and that a link to a document nobody has written yet is allowed.

Frontmatter for provenance and freshness

This is the rule most templates leave out, and the one that makes an agent-written knowledge base checkable later. Require every document to say who wrote it and when it goes stale. The Open Knowledge Format, an open specification published by Google Cloud, gives you the field names: type (the only required one), generated, verified, status, stale_after and sources. Using a published format means any tool that reads OKF understands your notes.

Source citation

Require a source for every number, date, name and quote, cited next to the claim. The guide to making agents cite sources goes deeper.

What agents must never do

Write the hard lines as "Never" rules: never mark something as checked by a person, never delete, never overwrite a person's edit. Anthropic's docs note that specific, concise instructions are followed more consistently than general ones.

How to record a check

When an agent confirms a document, it should say so in a fixed way: its own entry in verified with a timestamp. Then anyone can tell an agent's check from a person's.

Copy this into AGENTS.md at the root of your notes folder, then change the folder list to match yours. It stays under Anthropic's 200-line guideline with room to spare.

---
type: Instructions
title: Rules for agents
---
 
# Knowledge base: rules for agents
 
This folder is a knowledge base that people and agents write together.
Every file is plain markdown with YAML frontmatter (OKF v0.2).
Read this whole file before you change anything.
 
## Layout
 
- index.md in each folder lists what the folder holds. Read it first.
- log.md records what changed, newest first. Add a line for every session.
- company/     mission, glossary, how we work
- customers/   segments, interviews/ (one file per interview)
- metrics/     one file per metric; computations/ for approved queries
- decisions/   one file per decision, named YYYY-MM-DD-short-title.md
- references/  copies of source material you cite (PDF, CSV, saved pages)
- Never create a new top-level folder. Ask first.
 
## Finding things
 
- Start from the root index.md and follow links. Don't read every file.
- Search before you write. If a document on the topic exists, update it.
 
## Naming
 
- One concept per file. File names are lowercase-with-hyphens.md.
- index.md and log.md are reserved. Never use them for a document.
 
## Links
 
- Use standard markdown links, never [[wikilinks]].
- Link from the bundle root: [Churn](/metrics/churn.md).
- Linking to a document that doesn't exist yet is fine. Don't create
  an empty file just to fix the link.
- When you rename or move a file, update every link to it.
 
## Frontmatter
 
Every document starts with frontmatter. Keep keys you don't recognise
exactly as they are.
 
```yaml
---
type: Metric                # required: Metric, Decision, Interview, ...
title: Churn
description: One sentence, used in index.md and search.
status: stable              # draft | stable | deprecated
generated: { by: <your-name>/<version>, at: <UTC time, ISO 8601> }
stale_after: <UTC time>     # when this stops being safe to quote
sources:
  - id: billing-export
    resource: /references/billing-2026-09.csv
    title: Billing export, September 2026
---
```
 
- Sign every document you write or change in `generated`.
  Update `generated.at` on every meaningful change.
- Set `stale_after`: 90 days for metrics, 1 year for decisions.
- New documents start as `status: draft`.
 
## Sources
 
- Every number, date, name and quote needs a source.
- Add the source to `sources` with a short, stable `id`, then cite it
  after the claim with a footnote: Churn fell to 2.4%.[^billing-export]
- Only cite a source you opened in this session. Never invent a URL.
- If you can't find a source, write the claim under
  "## Open questions" instead of stating it as fact.
 
## Checking a person's edit
 
- Read the change, then every document that links to it or shares a
  source with it.
- If everything still matches, add yourself to `verified`:
  - { by: <your-name>/<version>, at: <UTC time> }
- If something no longer matches, propose the fix. Don't apply it silently.
 
## Never
 
- Never add a `human:` entry to `verified`. Only a person does that.
- Never remove or reorder someone else's `verified` entries.
- Never delete a document. Set `status: deprecated` and say why.
- Never overwrite a person's edit. If you disagree, say so and stop.
- Never edit files in references/. They are the evidence.
 
## When you finish
 
- Add a dated entry to log.md.
- List every file you created, changed, moved or deprecated.

Replace the retention periods under Frontmatter with your own. OKF counts every .md file except index.md and log.md as a document, so the template starts with its own frontmatter and a type to keep the bundle valid. The example frontmatter block inside is there for agents to copy.

Some rules only matter in one place. With AGENTS.md, put a second file in that folder, such as metrics/AGENTS.md; agents use the nearest one. Claude Code also has path-scoped rules: markdown files in .claude/rules/ with a paths field, loaded only when Claude reads a matching file.

---
paths:
  - "metrics/**/*.md"
---
 
# Metrics
 
- Every metric links to the query that computes it in metrics/computations/.
- Never change a number without a new source entry.

This keeps the root file short. Anthropic's docs warn that longer instruction files use more context and reduce adherence.

In Claude Code, run /context and look under Memory files to confirm your file loaded. With any agent, start a session by asking it to restate the rules for writing a new document. If it can't, the file isn't being read or is too long.

Then check the output, not the promise. Two greps catch the most common slips:

# documents with no type: the one required OKF field
grep -rL "^type:" --include="*.md" . | grep -v -e "/index.md$" -e "/log.md$"
 
# wikilinks that slipped in
grep -rn "\[\[" --include="*.md" .

When the same mistake shows up twice, add a rule for it. That's also Anthropic's advice for CLAUDE.md: write down what you'd otherwise explain again.

Knowtarium includes a skill that teaches Claude Code, Codex and Cursor the conventions of a Knowtarium knowledge base, so you don't have to write them into every instructions file.

What it teaches

• Read the index first. Follow links from index.md instead of loading every document.
• Sign what you write. Every change carries the agent's name in generated.by.
• Check after a person's edit. Read the connected documents, record the check in verified if everything still matches, and propose fixes if something doesn't.

How it pairs with your AGENTS.md

Some rules don't depend on anyone reading a file. In Knowtarium, agents can't mark anything as checked by a person, can't overwrite an edit you made (conflicts come to you), and can't skip your review. The app doesn't call an AI itself: when you want your edits checked, you ask your agent, and it follows the skill.

Chat apps without access to your files can connect to an optional MCP server that runs on your computer. See how agents work with Knowtarium.