The original title is: "Why monolithic AGENTS.md files don't scale—and a modular alternative"

Short summary

As coding agents like Codex and Claude Code evolved to explore entire repositories, monolithic AGENTS.md files have become a scaling problem—consuming context, mixing unrelated concerns, and becoming hard to maintain. OpenAI itself moved to a shorter AGENTS.md acting as a table of contents for a modular, versioned knowledge base. The article proposes a .harness directory convention to separate architecture, environment, validation, and workflow instructions into maintainable units.

• •Giant AGENTS.md files waste context and mix unrelated concerns for both agents and developers
• •OpenAI moved to a short AGENTS.md as an entry point to modular repository knowledge
• •Proposes .harness directory convention for versioned, maintainable agent instructions

Generated with AI, which can make mistakes.