A simpler way to make coding agents read less
After several months of tuning work with such as Codex and Claude Code, a simpler document-based workflow proved more reliable than many popular repositories, skills, frameworks, and shared workflows. The main setup uses a customized AGENTS.md file as the , plus 10 to 30 smaller markdown files in a /docs folder.
These files cover s, best practices, coding rules, things the AI should avoid, and project-specific knowledge. When one document becomes too large, it is turned into an file and split into smaller files.
The goal is to make the AI read only what matters for the current task instead of loading a huge knowledge dump every time. The workflow also includes a pre-validation step before the agent starts work, borrowing ideas from a repository.
Key points
- Keep AGENTS.md as the main instruction file for the agent.
- Store supporting knowledge in 10 to 30 smaller markdown files under /docs.
- Document s, coding rules, avoid-lists, and project-specific knowledge.
- Split oversized documents and use an file to point the agent to the right material.
- Add a pre-validation step before the agent starts making changes.