Emerging Markdown Formats That Shape Coding Agent Behavior

Project knowledge is moving beside source code, where coding agents can discover it and turn intent into implementation.

For years, the knowledge required to change software lived across architecture documents, ADRs, security reviews, wikis, tickets, incident reports, and the heads of experienced developers.

The repository held the implementation. Developers gathered the surrounding context, applied judgment, and translated both into code.

That boundary is changing. An agent-ready repository increasingly carries not only source code, tests, configuration, and dependencies, but also the knowledge required to change them correctly.

A growing family of Markdown files captures that knowledge in forms coding agents can discover and use. Together, these files create a metacode layer: human intent and judgment made legible to the agent.

1. Onboarding and standing rules

A human joins a project once. A coding agent effectively onboards whenever it begins a task.

AGENTS.md is the closest thing to a neutral README for agents. It can describe repository structure, build and test commands, coding conventions, and pull request expectations. Nested files can add rules for a package or subsystem.

Vendor-native alternatives serve the same role: CLAUDE.md and .claude/rules/, GEMINI.md, GitHub Copilot instruction files, and .clinerules/.

These files answer: What should remain true across many tasks?

2. Skills package repeatable procedures

Standing rules are not the same as a procedure.

An agent skill describes how to perform a particular kind of work. A database migration skill might inspect the schema, create the migration, update generated types, run compatibility checks, verify rollback, and prepare the review summary.

The open Agent Skills specification packages this workflow in a required SKILL.md, with optional scripts, references, templates, and assets.

The boundary is useful:

• AGENTS.md carries standing context and constraints.

• SKILL.md carries a repeatable procedure invoked for a specific task.

3. Specs, plans, and tasks make change intent reviewable

Design and planning disappear when they exist only in chat. Versioned Markdown turns them into artifacts people can review before an agent implements them.

GitHub Spec Kit uses a clear chain:

• spec.md records requirements and the desired outcome.

• plan.md explains the technical design and implementation approach.

• tasks.md breaks the plan into executable units.

• The agent implements and validates the change.

OpenSpec, Kiro Specs, and project-specific PLANS.md files use different conventions, but they converge on the same separation: requirements, design, plan, tasks, implementation, and validation.

4. Domain files carry specialized context

Generic onboarding cannot fully describe every system.

ARCHITECTURE.md can capture system boundaries, dependencies, NFRs, and long-lived decisions. DESIGN.md can carry visual and design-system intent. AUTH.md can describe an authentication recipe. REVIEW.md can define code-review priorities and verification expectations.

Their maturity differs. ARCHITECTURE.md is an established documentation convention, while several domain-specific formats remain vendor-specific or experimental. The direction is nevertheless clear: specialized engineering knowledge is becoming directly legible to agents.

read image descriptionALT

5. Memory makes learned context durable

Some knowledge is designed in advance. Other knowledge appears only while software is built and operated.

Agent memory preserves lessons such as an unexpected build prerequisite or a recurring debugging pattern across sessions. Claude Code makes an important distinction: humans write shared project guidance, while the agent writes auto memory into MEMORY.md and topic files stored outside the repository.

Machine-local memory should not silently become team truth. A practical promotion path is:

• The agent records a tentative observation locally.

• A human reviews it when it recurs or affects shared work.

• Durable knowledge moves into a project rule, skill, ADR, or domain document.

Tentative knowledge stays local. Reviewed knowledge becomes shared.

read image descriptionALT

Put the metacode layer together

A project does not need every file. Use the smallest set agents can reliably discover. Keep reviewed knowledge beside the source code, and use vendor-specific files as thin compatibility bridges when another file is canonical.

The repository is becoming the meeting point between source code and metacode: requirements, NFRs, architecture, design, rules, procedures, plans, and durable learning.

When agents can read both, they act as intent compilers. Source code becomes the executable byproduct of human intent and judgment made legible to the agent.

The engineering task is to keep that metacode scoped, reviewed, and current. It does not replace testing or review. It gives the next code change a better source.

The full article includes the detailed format landscape, maturity notes, examples, and primary sources:

https://generativeprogrammer.com/p/emerging-markdown-formats-that-shape