Files

Defame1297 c0ede4b22e feat: implement governance instruction layer Phase 1

2026-05-15 08:55:11 +00:00

14 KiB

Raw Permalink Blame History

Agent Instructions — Research & Design Notes

Purpose: Documents the research behind AGENTS.md and the design decisions made in producing it. Provides implementation guidance for deploying agent instructions across tools. Human reference — does not go into agent context.

Repo note: AGENTS.md was integrated into this repo as core/instructions/governance.md and is loaded globally via @import in providers/claude-code/CLAUDE.md. References to AGENTS.md throughout this document are the generic concept (any agent instruction file following this pattern) and the historical name — not a path in this repo.

Why a Separate Agent Instructions File?

The AI Constitution (ai-constitution.md) is a governance document for humans and agents — comprehensive, reasoned, cross-referenced. It is too long for global agent context: every token in a system prompt costs tokens on every inference, and research confirms long instruction files are largely ignored.

The agent instructions file (AGENTS.md) is the operative distillation: only principles an agent can act on in the moment, stripped of rationale, short enough to load without meaningful context cost.

Research Findings on Effective Agent Instructions

Instruction following: the compliance ceiling

AGENTIF benchmark (Tsinghua University, 2025), evaluating 707 instructions across 50 real-world agentic applications (average 1,717 tokens, ~11.9 constraints per instruction): the best model perfectly follows fewer than 30% of instructions. This is the current ceiling for complex multi-constraint agentic instruction following. Source: keg.cs.tsinghua.edu.cn/persons/xubin/papers/AgentIF.pdf.

A broader evaluation of 256 models across 20 diagnostic tests found an overall pass rate of 43.7% on instruction following, with performance ranging from 0% to 100% and a standard deviation of 28.4 percentage points. Provider methodologies significantly impact adherence beyond model size. Source: huggingface.co/richardyoung/llm-instruction-following-paper.

Implication: AGENTS.md improves compliance; it does not guarantee it. The constitution's principle — "deterministic enforcement must sit outside the AI" — is the primary enforcement mechanism. Agent instructions are a supplementary signal.

Instruction length: the 500-line limit

Practitioners analysing 2,500+ repositories: "If your config file is over 500 lines, most of it is being ignored. LLMs have limited instruction-following capacity — a focused 50-line file outperforms a sprawling 1,000-line one." Source: deployhq.com/blog/ai-coding-config-files-guide.

Research on hierarchical prompting (HIPO, 2025): processing lengthy prompts increases latency and computational cost as self-attention scales quadratically with sequence length. Source: arxiv.org/pdf/2603.16152.

Design decision: AGENTS.md targets under 80 lines. Every line must earn its place.

Priority ordering: hard constraints first

HIPO research: hierarchical prompting with priority-ordered directives is the standard for reliable agentic instruction following. The system prompt defines global behavioral guidelines and safety boundaries; higher-priority instructions must appear first. Source: arxiv.org/pdf/2603.16152.

Design decision: AGENTS.md opens with Hard Prohibitions (the Never rules), then Required Behaviours. Prohibitions come first because they are unconditional and must not be overridden by task context.

Hard prohibitions vs. behavioural guidance

Contrary to the intuition that unconditional prohibitions are the most reliable instruction type, Semantic Gravity Wells (2026) found that ~87.5% of negative-constraint failures are priming failures — stating the forbidden token ("Never hardcode a password") activates the concept and increases the likelihood of exactly that behaviour in models trained on next-token prediction. Condition-based constraints account for ~42.6% of real-world applications and are the most commonly failed instruction type. Source: AGENTIF benchmark; Semantic Gravity Wells (2026).

Design decision: Every "Never X" in AGENTS.md is paired with "— instead do Y." This converts a negative constraint into a positive directive, avoiding the priming failure mode while retaining the unconditional framing. The Required Behaviours section improves compliance without guaranteeing it — they guide probabilistic behaviour in the right direction.

Including examples

Research confirms agents learn implicitly from examples even within a single prompt. Infobip documentation: "Providing sample outputs helps the agent understand the expected output format. You can show both correct and incorrect examples to make behaviour consistent." Source: infobip.com/docs/ai-agents/advanced-topics/write-prompts.

Design decision: AGENTS.md v1.1 pairs every prohibition with a positive alternative (the primary example pattern). Concrete negative examples (e.g., showing a hardcoded credential) remain a v1.2 candidate if compliance testing reveals persistent violations of specific rules.

What linters handle: exclude from agent instructions

"Do not include things a linter handles — these are Prettier's job, not your AI config file's job." Source: deployhq.com.

Design decision: Code formatting, import ordering, naming conventions, and other statically enforceable rules are excluded. These are enforced by CI gates, not by agent instructions.

Design Decisions in AGENTS.md

Included: agent-actionable principles

These are things an agent can act on in the moment:

Secrets and credentials handling (detect, refuse, redirect)
Data classification before sharing (apply the four-tier framework)
Production action gates (stop and confirm for irreversible/high-stakes)
Code security review before committing
Honesty over agreement (re-evaluate vs. capitulate; flag uncertainty)
Deterministic code preference for repeatable tasks
Agentic transparency (state intent, prefer reversible, log actions)
Prompt/model hygiene (version prompts, right-size models)

Excluded: human process decisions

These cannot be operationalised by agent instructions — they are enforced by humans, tooling, or organisational process:

HITL checkpoint requirements (the human decides when to apply these)
Post-mortem requirements (human process)
IP licence scanning (tooling: Black Duck, FOSSA, etc.)
Regulatory notification (human/legal process)
Sustainability measurement (organisational)
Audit log retention periods (infrastructure/policy)
EU AI Act compliance verification (legal/compliance function)
Deskilling / skill atrophy monitoring (Constitution §5): detecting whether AI-assisted roles are losing baseline capability is a human governance obligation — an agent cannot assess its own contribution to skill atrophy in the human it assists. Governance mechanism design is out of agent scope.
Diverse perspectives prompting (Constitution §4): this is a human prompting standard — the obligation is on the person constructing the prompt to ask for multiple viewpoints on contested questions. An agent could volunteer diverse perspectives proactively, but this conflicts with following instructions faithfully and is too context-dependent to encode as a blanket agent rule. Left as a human prompting principle.
Deterministic enforcement controls (Constitution Governance section): pre-commit hooks, CI gates, scanner configuration, audit logging infrastructure, AI agent permission scoping, and environment verification are specified in CONTROLS.md and implemented by humans. These cannot be operationalised by agent instructions — they run mechanically regardless of agent or human intent.

The data classification table

Included as a quick-reference decision rule — the most token-efficient addition to the file. Agents can apply the four tiers instantly without loading the constitution.

Deployment: Single Source of Truth + Thin Adapters

AGENTS.md is the single source of truth. Do not copy-paste its content into tool-specific files. Instead, create thin adapter files that reference it.

Global vs per-repo deployment

This is the first architectural decision to make. It shapes every path reference below.

Per-repo (recommended starting point): AGENTS.md lives at the root of each repository. Tool adapters (CLAUDE.md, copilot-instructions.md, etc.) sit alongside it and reference it by relative path. Simple, no cross-tool path issues, version-controlled with the codebase it governs. When you update AGENTS.md for one repo, only that repo is affected — deliberate isolation.

Global (team or personal baseline): AGENTS.md lives in a central location, and a global tool config references it. For Claude Code the global CLAUDE.md is ~/.claude/CLAUDE.md; for Copilot there is no equivalent global file. The benefit: one AGENTS.md update applies everywhere. The cost: cross-tool path handling becomes complex (see below), and per-repo customisation requires an additional local override layer.

Recommended pattern: Start per-repo. Once you see the same AGENTS.md content appearing in multiple repos unchanged, extract a global baseline and use the import/reference pattern described below. Do not over-engineer the global layer before you know what belongs in it — this is the same principle that governs skills library design.

Path handling

When AGENTS.md and the adapter file are in the same directory (per-repo pattern), relative paths work for all tools. When they are not in the same directory (global pattern), each tool handles paths differently:

Claude Code supports @import syntax and symlinks:

# CLAUDE.md — simplest per-repo adapter
@AGENTS.md

This imports AGENTS.md directly at session start. No path issue if both files are in the repo root. For a global setup with AGENTS.md in ~/.claude/, place CLAUDE.md alongside it and use the same @AGENTS.md relative reference — Claude Code loads ~/.claude/CLAUDE.md for every project automatically.

On Unix, a symlink eliminates duplication entirely:

ln -s AGENTS.md CLAUDE.md

On Windows, use the @AGENTS.md import instead (symlinks require Developer Mode).

Copilot and Cursor reference AGENTS.md by path string in prose — not a live import. If AGENTS.md is not in the repo root, update the prose reference to the actual path, or keep a copy in the repo. There is no global Copilot instructions file; .github/copilot-instructions.md is per-repo only.

GitHub Copilot

Create .github/copilot-instructions.md:

Follow the governance rules in `AGENTS.md` at the root of this repository at all times.

Since July 2025, Copilot also supports scoped instructions via .github/instructions/*.instructions.md with glob-pattern frontmatter for file-type specific rules. Source: code.visualstudio.com/docs/copilot/customization/custom-instructions.

Claude Code

Create CLAUDE.md (or use the @import / symlink approach above):

@AGENTS.md

Or, if you want to add Claude-specific rules on top:

@AGENTS.md

## Claude-specific additions
For full governance context, see `ai-constitution.md`.

Cursor

Create .cursor/rules/governance.mdc:

---
alwaysApply: true
---
Follow the governance rules in `AGENTS.md` at the root of this repository at all times.

Gemini CLI

Create GEMINI.md:

Follow the governance rules in `AGENTS.md` at the root of this repository at all times.

Why this pattern

Source: deployhq.com — "Maintain one source of truth (AGENTS.md) and have tool-specific files reference it. Don't copy-paste the same rules into CLAUDE.md, .cursorrules, and copilot-instructions.md." When AGENTS.md is updated, all tools pick up the change without manual synchronisation.

Claude Code's @import syntax (confirmed 2026) means the thin adapter for Claude Code can be a single line. Source: blink.new/blog/agents-md-vs-claude-md.

Known Limitations

Compliance ceiling is ~30% on complex multi-constraint tasks. Unconditional single-directive rules (with positive alternative framing) have substantially higher compliance than conditional behavioural guidance. But "Never X — instead do Y" is not a guarantee of compliance; it is a best practice for reducing priming failures. Semantic Gravity Wells (2026) found negative constraints without positive alternatives fail ~87.5% of the time via priming. Design accordingly.
Prompt injection can bypass agent instructions. Malicious content in repository data (PR bodies, issue descriptions, code comments) can override system-level instructions in some models. This is why HITL gates for production actions are in the constitution as non-negotiable process controls, not in AGENTS.md as agent instructions alone.
Instruction drift. Agents operating over long contexts may lose earlier instructions. Keep AGENTS.md short. For agentic workflows with many steps, consider injecting a reminder of the most critical Never rules at task boundaries.
Tool-specific parsing differences. Not all tools process AGENTS.md identically. Validate compliance behaviour per tool when onboarding a new AI assistant.

When to Update AGENTS.md

When the AI Constitution is updated (AGENTS.md must stay consistent with it)
When a new AI tool is onboarded and its parsing behaviour differs materially
When a hard prohibition is regularly violated in practice (may need reformulation or a concrete example added)
When a new high-risk pattern is identified that agents can detect and refuse in context
At minimum: annually, aligned with the constitution review cycle

Do not add principles that belong in the constitution (reasoned governance) or that belong in tooling (linters, scanners, CI gates). AGENTS.md covers only what agents can act on in the moment.

Created: May 2026. Companion to AGENTS.md v1.0 and AI Constitution v1.0.

14 KiB Raw Permalink Blame History