Designing AGENTS.md and CLAUDE.md

AGENTS.md or CLAUDE.md should be a compact operating contract, not an essay. It should tell the model where to look, what it may write, how to run the three operations, and what must be reported back.

Principles

• Keep the file short enough that an agent can obey it.
• Name read-only and writable directories explicitly.
• Use deterministic page shapes and metadata fields.
• Define ingest, query, and lint as separate workflows.
• Require a final changed-files and verification summary.

Minimal AGENTS.md template

# LLM Wiki Agent Instructions

## Purpose
Maintain this markdown LLM Wiki by compiling raw sources into durable, linked wiki pages.

## Directories
- raw/: read-only source material. Never edit, move, or delete.
- wiki/: compiled markdown knowledge graph. You may edit under these rules.
- wiki/index.md: required content catalog. Update after every approved write.
- wiki/log.md: append-only action log. Never rewrite prior entries.

## Page Shape
Every wiki page must include:
- title
- type: concept | entity | source-summary | synthesis | contradiction | runbook
- status: draft | reviewed | needs-update | archived
- source_status: source-linked | source-needed | derived
- related: list of wiki paths or [[wiki-links]]

## Ingest
When asked to ingest a file:
1. Read the raw source without editing raw/.
2. Create or update one wiki/sources/ summary.
3. Extract Summary, Key Claims, Evidence, Entities, Connections, Contradictions.
4. Update relevant concept/entity/synthesis pages.
5. Preserve existing unresolved claims unless a human approves resolution.
6. Update wiki/index.md and append to wiki/log.md.

## Query
When asked a question:
1. Read wiki/index.md first.
2. Open the smallest useful page set.
3. Cite local wiki paths in the answer.
4. Mark unsupported claims as unsupported.
5. Ask before saving new synthesis.

## Lint
Check broken links, orphan pages, missing frontmatter, stale claims, contradictions, and missing sources.
Do not delete pages without explicit human approval.

## Final Response
Report files changed, sources used, contradictions found, and checks performed.

Metadata fields

Context pollution warning

Do not load the schema with philosophy, marketing copy, or every possible edge case. Long instruction files can increase token cost and make agents less reliable. Put durable project truth in wiki pages and keep the root schema focused on actions and boundaries.