docs: restructure AGENTS.md for parseability and single source of truth

[fkakatie]

TL;DR: Restructures AGENTS.md to be clearer, non-duplicative, and easier for agents to follow. No functional changes.

Test URLs:

• Before: https://main--aem-boilerplate--adobe.aem.live/
• After: https://agents-restructure--aem-boilerplate--adobe.aem.live/

---

What's different (and why!)

AGENTS.md treated as a persistent instruction layer: Claude Code and similar agents load project instruction files at session start and retain them as persistent context across interactions. This makes AGENTS.md the most reliable location for durable behavioral rules and executable instructions. ^{1 2}

Commands moved to the top: Agents process instruction files sequentially. Published guidance recommends putting executable commands first so agents encounter runnable instructions immediately rather than scanning prose. ^{3 4}

Requirements consolidated into a single source of truth: Performance, accessibility, security, and testing requirements were merged into a single Requirements section. Guidance consistently recommends avoiding duplication and maintaining one authoritative location per rule to prevent conflicts and drift. ^{3 4 5}

Explicit, discrete rules instead of bundled guidance: Multi-rule bullets were split into individual, imperative rules. This improves parseability and reduces ambiguity, which is specifically recommended for agent instruction files. ^{3 6}

Reduced duplication and file size: Removed redundant explanations and consolidated overlapping sections. Instruction files are persistent context and benefit from being concise and unambiguous. ^{7 4}

Standardized structure and predictable scan order: Sections and formatting were normalized so both mere mortals and agents can reliably locate commands, requirements, environments, and workflows. Real-world reference implementations follow similar structural conventions. ^{8 5}

Alignment with Helix and David’s Model: The document explicitly reinforces intuitive authoring, clear author–developer contracts, and avoidance of hidden conventions consistent with Helix principles. ^{9 10}

Impact

Documentation-only change. No functionality change or authoring impact.

References

1. Claude Code overview
2. Claude Code memory
3. GitHub blog: Lessons from 2,500 repositories
4. OpenAI Codex AGENTS.md docs
5. openai/codex AGENTS.md
6. awesome-agents-md
7. How Claude Code works
8. agents.md
9. Helix Manifesto
10. David's Model

[aem-code-sync]

Hello, I'm the AEM Code Sync Bot and I will run some actions to deploy your branch and validate page speed.
In case there are problems, just click a checkbox below to rerun the respective action.

• Re-run PSI checks
• Re-sync branch

Commits

• 4b210c7 ✅ (latest)

[aem-code-sync]

	Page	Scores	Audits	Google
📱	/
🖥️	/

[fkakatie]

Obviously needs to be road tested, so will remain in draft.