AIAgents on emsenn.net

AGENTS.md

Sat, 07 Mar 2026 00:00:00 +0000

AGENTS.md is a markdown file checked into a git repository that customizes how AI coding agents behave. It sits at the top of the conversation history, below the system prompt, and loads on every request.

Origin and adoption

The AGENTS.md convention started as a collaborative effort by Sourcegraph and is now maintained by the Agentic AI Foundation under the Linux Foundation. It has been adopted by OpenAI (Codex), Google (Gemini CLI, Jules), GitHub Copilot, Cursor, Windsurf, Aider, Zed, Warp, Roo Code, AMP, and others. It aims to replace vendor-specific files (CLAUDE.md, GEMINI.md, COPILOT.md) with a single shared standard.

CLAUDE.md

Sat, 07 Mar 2026 00:00:00 +0000

A CLAUDE.md file is a markdown document that Claude Code reads at the start of every conversation. It provides persistent, project-specific context that the agent cannot infer from code alone.

Load order

Claude Code loads CLAUDE.md files from four locations, additively:

Global (~/.claude/CLAUDE.md) — personal preferences, all projects
Project root (./CLAUDE.md) — committed to version control, shared
Subdirectory (path/to/dir/CLAUDE.md) — loaded lazily when Claude works in that directory
User-specific (.claude/CLAUDE.md) — personal overrides, gitignored

Ancestor files load at startup. Subdirectory files load lazily when the agent touches files in that directory. Sibling directories never cross-load.

Progressive Disclosure in Agent Instructions

Sat, 07 Mar 2026 00:00:00 +0000

Progressive disclosure is an information architecture principle applied to AI agent instruction files. The root instruction file (CLAUDE.md or AGENTS.md) contains only universally applicable rules. Task-specific, domain-specific, or tool-specific instructions live in subdirectory files, skill documents, or referenced specifications.

Why it matters

Every token in a root instruction file loads on every request. Long root files create three problems:

Budget pressure — instruction-following quality degrades as instruction count rises.
Relevance dilution — instructions irrelevant to the current task compete for attention with relevant ones.
Staleness risk — more content means more surface area for drift between instructions and actual project state.

The layering pattern

Layer	File	Loaded when	Contains
Root	`CLAUDE.md` (repo root)	Every session	Build commands, architectural constraints, what not to touch, pointers to key files
Subdirectory	`subdir/CLAUDE.md`	When working in that directory	Local conventions, tool-specific setup, domain rules
Skill	`skills/*/SKILL.md`	When skill is invoked	Detailed operational instructions for one task
Reference	Specification or guide files	When agent reads them on demand	Full style guides, formalization protocols, domain specs

In this repository

The emsenn.net repository applies progressive disclosure across two layers: