Designing AGENTS.md and CLAUDE.md

AGENTS.md or CLAUDE.md should be a compact operating contract, not an essay. Pair it with a short readme.human when people need plain guidance about what to clarify before steering AI work, and move long history into cold memory before it becomes the default startup load.

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.
Keep hot context focused on current truth; point to cold memory for older evidence.
Require a final changed-files and verification summary.

Two useful levels

Level	Use when	Required files
Local-only LLM Wiki	One person or a small private team needs durable markdown memory without formal project transfer.	`AGENTS.md`, `raw/`, `wiki/index.md`, `wiki/log.md`, page templates.
Handoff-ready LLM Wiki	Another AI, team, or maintainer must safely resume work without private chat history.	`AGENTS.md`, `readme.human`, `.uai/context.uai`, `.uai/stack.uai`, `.uai/constraints.uai`, and optional progress/operations/style files.

When to split instructions into .uai files

Trigger	Keep in `AGENTS.md`	Move to topic files
The root file is getting too long.	Load order, hard constraints, required first response, and exact current task rules.	Detailed context, architecture, operations, style, decisions, and progress history.
Multiple agents need stable onboarding.	Which files to load, which targeted checks fit ordinary work, and when full release checks are out of scope.	Durable state that should survive chat history loss.
Humans need steering help.	Machine-facing behavior and red lines.	Human-facing briefing in `readme.human`, not private chat.
New files arrive out of band.	The requirement to scan intake and disposition every active file.	Generated intake index and file-handoff operating notes.
Topic files start repeating old build history.	The current conclusion, current rule, and pointer to recovery evidence.	Cold-memory archive, source summary, dated log, or LLM Wiki page.

Handoff-ready starter tree

project-wiki/
  AGENTS.md
  readme.human
  .uai/
    context.uai
    stack.uai
    constraints.uai
    progress.uai
    operations.uai
    test-plan.uai
    style.uai
  agent-file-handoff/
    Content/
    Improvement/
    Archive/
  raw/
  wiki/
    index.md
    log.md
    concepts/
    sources/
    syntheses/
    contradictions.md

AGENTS.md frontmatter

---
uaix: "1.0"
type: agents
project: "Project Name"
updated: "YYYY-MM-DD"
status: active
---

# Project AI Instructions

## Loaded Context
@uai[.uai/context.uai]
@uai[.uai/stack.uai]
@uai[.uai/constraints.uai]
@uai[.uai/test-plan.uai]

Recommended load order

Read root AGENTS.md.
Read readme.human as the human briefing, not as an override.
Scan agent-file-handoff/Content/ and agent-file-handoff/Improvement/; ignore Archive/ unless a human explicitly names it.
Refresh the intake index if the project has one, then inspect and disposition every active file.
Load the listed .uai files and summarize purpose, surface, constraints, intended edits, targeted checks, and any full release checks that are out of scope before broad work.

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, targeted checks performed, and any package or release checks intentionally not run.

Metadata fields

Field	Purpose	Example
title	Human and index label.	Incremental Compilation
type	Routing and lint classification.	concept
status	Review state.	reviewed
source_status	Evidence posture.	source-linked
related	Graph connections.	[[provenance]], [[index.md]]
last_reviewed	Freshness signal.	2026-04-27

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, keep the root schema focused on actions and boundaries, and put human-facing steering advice in readme.human.

Support boundary

AGENTS.md, readme.human, and .uai files are project handoff context. They are not UAI-1 conformance evidence by themselves. A test-plan.uai file should control check selection for the local project, including the rule that full builds clean and update private source docs without publishing them. Public UAI-1 claims still need canonical UAIX pages, schemas, validator results, release notes, or implementation evidence.