docs: add documentation philosophy to AGENTS.md

Dmitry Gruzdrequested to merge
docs/add-agents-philosophy into main

What does this MR do and why?

Adds a "Documentation Philosophy" section to AGENTS.md that establishes clear guidelines for keeping the file lean and focused.

Problem: AGENTS.md is growing (currently ~190 lines). Without guidelines, it risks becoming unwieldy and difficult to navigate, reducing its effectiveness as a quick reference.

Solution: Document a philosophy that encourages:

  • Keeping AGENTS.md around 100-150 lines
  • Focusing on workflows, quick reference, and mental models
  • Extracting detailed content to doc/ subdirectories with links

This sets expectations for future contributors and provides a clear path for managing documentation growth.

Context: This came up during review of !326 (merged), which added valuable architectural considerations but increased the file size. Having this philosophy documented will help guide future decisions about what stays in AGENTS.md vs. what gets extracted.

Related: !326 (merged), #80 (closed)

How to set up and validate locally

Read the updated AGENTS.md to verify the philosophy section is clear and well-positioned.

Merge request reports