AGENTS.md

Get the template

No GitHub account needed. Right-click and “Save As” to download.

Download AGENTS.md View on GitHub View filled example

AGENTS.md is the central document that AI assistants read when entering your project. It defines principles, project context, documentation standards, and compliance auditing — everything an AI needs to work effectively in your codebase.

What it contains

AGENTS.md is structured in sections:

Section	Purpose
Header	Project name, status, repo info, version metadata
Important Context	Critical background the AI must know
11 Core Principles	Mandatory development rules (KISS, TDD, SOC, DRY, etc.)
Documentation Standards	AI-optimized documentation principles (Principle 5.5)
Jimmy’s Workflow	Validation checkpoint overview with link to full doc
Project Architecture	Service overview, dependencies, environment
Known Issues	Current bugs and limitations
Project-Specific Guidelines	Rules unique to this project
Common Patterns	Code patterns and conventions
Troubleshooting	Common problems and solutions
Template Versioning	Version tracking and sync instructions
Compliance Auditing	How to verify project follows the rules

The 9 project-specific sections

The template has 9 sections marked with <!-- PROJECT_SPECIFIC START --> and <!-- PROJECT_SPECIFIC END --> comments. These are the sections you must fill in:

<!-- PROJECT_SPECIFIC START: IMPORTANT_CONTEXT -->
Your critical project background here
<!-- PROJECT_SPECIFIC END: IMPORTANT_CONTEXT -->

Section	What to write	Example
IMPORTANT_CONTEXT	Background, history, constraints	”This is a Tauri v2 app using SolidJS for the frontend”
SERVICE_OVERVIEW	Architecture, components, data flow	Table of services with ports and responsibilities
CURRENT_STATUS	What works, what’s in progress	Checkbox list of features and their state
KNOWN_ISSUES	Bugs, limitations, workarounds	Numbered list with severity and notes
PROJECT_SPECIFIC_GUIDELINES	Rules unique to this project	”All API responses must use the Result type”
COMMON_PATTERNS	Code patterns, naming conventions	Code snippets showing the expected pattern
DEPENDENCIES	External services, APIs, databases	Table with name, purpose, and connection details
ENVIRONMENT_VARIABLES	Required env vars	Table with var name, description, and example
TROUBLESHOOTING	Common problems and fixes	”If X fails, check Y” format

The 11 Core Principles

Every AGENTS.md includes these principles. They are non-negotiable and persist even after AI context compression:

1. KISS — Keep It Simple, Stupid
2. TDD — Test-Driven Development
3. SOC — Separation of Concerns
4. DRY — Don’t Repeat Yourself
5. Documentation Standards — Factual, dated, objective
6. AI-Optimized Documentation (5.5) — Structured data for humans AND AI
7. Jimmy’s Workflow — Red/Green checkpoints (mandatory)
8. YAGNI — You Ain’t Gonna Need It
9. Fix Now — Never defer known issues
10. Measure Twice, Cut Once — Verify before executing
11. No Shortcuts — Complete the job properly

Plus Rule 11: Rules Persist — All rules remain in effect after context window compression.

See the full 11 Core Principles reference.

Principle 5.5: AI-Optimized Documentation

This is one of the more distinctive features. It defines 7 principles for documentation that works for both humans and AI:

1. Structured Data Over Prose — Tables, JSON, YAML instead of paragraphs
2. Explicit Context — Never assume prior knowledge
3. Cause-Effect Relationships — Clear “if X then Y” statements
4. Machine-Readable Formats — Consistent dates, versions, status values
5. Searchable Content — Keywords, anchors, consistent terminology
6. Version-Stamped — Date all documentation updates
7. Cross-Referenced — Explicit links between related docs

The agents.md standard

AGENTS.md follows the agents.md standard — a community convention for AI-readable project files. CLAUDE.md references AGENTS.md, ensuring any AI tool that reads either file discovers the full project context.

Template versioning

AGENTS.md includes version metadata in an HTML comment:

<!--
TEMPLATE_VERSION: 1.7.0
TEMPLATE_SOURCE: templates/core/AGENTS.md.template
LAST_SYNC: 2026-01-29
-->

Use the provided tools to check and sync versions (from inside the cloned repo):

cd Ydun_ai_workflow
templates/tools/check-version.sh     # Check if up to date
templates/tools/sync-templates.sh    # Sync while preserving customizations

Getting started

1. Copy the template (from inside the cloned repo): cp templates/core/AGENTS.md.template ./AGENTS.md
2. Fill all 9 PROJECT_SPECIFIC sections
3. Verify: grep -rn "\[.*\]" AGENTS.md | grep -v http
4. Read the AGENTS Template Guide for detailed section-by-section guidance