emsenn

Agent instructions derive from policies

3 min read

Context

CLAUDE.md and AGENTS.md files are currently hand-written. They contain a mix of setup instructions, conventions, and constraints. When policies change, the agent instruction files do not automatically reflect those changes. The instructions duplicate information that exists elsewhere (in policies, in the directory organization spec, in domain ASR specs) without a clear relationship to those sources.

emsenn observed (2026-03-07): “CLAUDE.md and AGENTS.md should probably be collections of the most important policies in a directory and the terms needed to understand those policies.”

Decision

Agent instruction files (CLAUDE.md, AGENTS.md) should be understood as rendered collections of:

  1. Applicable policies — the policies that apply in this directory, collected from the directory itself and all parent directories, resolved for precedence.
  2. Essential terms — the vocabulary needed to understand those policies in this directory’s context.
  3. Setup instructions — concrete commands needed to work in this directory (environment setup, build commands, etc.).

Policies are the source of truth. Agent instructions are the presentation layer.

Policy inheritance model

Policies apply from the top down. A policy in a parent directory applies to all subdirectories unless a lower-level policy explicitly overrides it. Lower-level policies that contradict parent policies take precedence (specificity wins, like CSS).

The inheritance chain for a file at mathematics/concepts/proof/index.md is:

personal/projects/emsemioverse/policies/  (project-level)
  → mathematics/policies/                 (discipline-level, if exists)
    → mathematics/concepts/proof/policies/ (topic-level, if exists)

An agent working in mathematics/ should read the project-level policies and any mathematics-specific policies, with the latter overriding the former on points of conflict.

Implication for AGENTS.md generation

AGENTS.md files could eventually be generated by a script that:

  1. Resolves the policy inheritance chain for that directory
  2. Extracts the most important constraints as terse statements
  3. Lists the essential terms (from terms/ in the directory and parents)
  4. Includes any directory-specific setup instructions

This is a target architecture, not an immediate requirement. Hand-written AGENTS.md files remain valid as long as they are consistent with the policies. The generation step is part of plan 0003 (policy encoding).

Consequences

  • Policies become the single source of truth for constraints
  • AGENTS.md files should reference policies rather than restating them
  • When policies change, AGENTS.md files may need updating (manually now, automatically once generation is implemented)
  • The policy inheritance model needs a resolution script (plan 0003)

Alternatives considered

  • Keep AGENTS.md as hand-written documents: simpler, but leads to drift between policies and instructions. Information lives in two places with no mechanism to keep them synchronized.
  • Replace policies with AGENTS.md entirely: loses the machine-readable, composable, inheritable structure. AGENTS.md is prose; policies can be structured data.

Graph View

Backlinks