AGENTS.md Integration

The simplest integration path. Add a ## Modernization Context section to your project’s root AGENTS.md file. Every major AI coding agent reads this file automatically.

Who Reads It

Claude Code, GitHub Copilot, Codex CLI, Cursor, Gemini CLI, Amp, Aider, Zed — every major agent.

How It Works

A ## Modernization section in the project’s root AGENTS.md is automatically concatenated into the agent’s prompt at session start. The agent reads the prose and follows the instructions via LLM instruction-following.

Template

Copy this into your AGENTS.md:

## Modernization Context

This project is undergoing legacy modernization. Read `.agents/modernization/manifest.json`
for full context.

**Bounded Contexts:** Accounts (core, in-progress), Stock (supporting, not started)
**Current Phase:** Phase 1 — Core Accounting extraction
**Extraction Pattern:** Strangler Fig with behavior-preservation parity tests
**Parity Status:** 68/72 tests passing (94.4%)

Before modifying any legacy code, check:
1. `.agents/modernization/domains.json` — which bounded context owns this code
2. `.agents/modernization/complexity.json` — extraction tier and risk
3. `.agents/modernization/extraction-plan.json` — sequencing constraints

Customization

Adjust the template to match your project:

For a Django Project

## Modernization Context

Migrating from Django 3.2 / Python to TypeScript / NestJS.
Pattern: Strangler Fig. Architecture: Hexagonal.

**Active extraction:** Orders module (35 models → 20 services)
**Parity:** 45/52 tests passing (86.5%)

Key files:
- `.agents/modernization/manifest.json` — project overview
- `.agents/modernization/domains.json` — 8 bounded contexts mapped
- `.agents/modernization/complexity.json` — 3 God-classes identified

Rules:
- Do NOT modify legacy code without checking extraction-plan.json
- Run parity tests after any change to extracted modules
- Update migration-state.json when completing entity migration

For a COBOL Project

## Modernization Context

Migrating from COBOL to Java/Spring Boot.
Pattern: Strangler Fig. Architecture: Clean Architecture.

**Scale:** 2.1M lines of COBOL across 340 programs
**Active extraction:** Claims Processing (Phase 1 of 4)
**Parity:** Shadow testing via traffic mirroring

Key files:
- `.agents/modernization/manifest.json` — program inventory
- `.agents/modernization/domains.json` — 12 bounded contexts
- `.agents/modernization/complexity.json` — copybook dependency analysis

Strengths and Limitations

Aspect	Detail
Strength	Works with every agent today. Zero setup.
Strength	No dependencies, no tooling required.
Strength	Human-readable — developers benefit too.
Limitation	Prose instructions, not structured data.
Limitation	Agent interprets via LLM, not parser.
Limitation	Read-only — agent cannot update progress.

Combining with Other Mechanisms

The AGENTS.md section works as a pointer and summary. The detailed data lives in the JSON files. When combined with Mechanism B (Agent Skill) or Mechanism C (MCP Server), the AGENTS.md section serves as a fallback for agents that do not support skills or MCP.

Next Steps

• Agent Skill Integration — Progressive disclosure for skill-aware agents
• MCP Server Integration — Deterministic tool access