This report was generated by running /agentlint on a production Symfony project with a Docker-based development environment, multi-tenant architecture, and payment integration.
The original AGENTS.md was 2,202 words. After applying the fixes, it dropped to 268 words - an 88% reduction.
agentlint report
File: AGENTS.md
Word count: 2,202 (target: <800)
Sections: 10 + subsections
---
Issues found
[HIGH] Rule 1: No codebase overviews
Lines affected: 398-470 (Project Structure section)
Problem: Full directory tree listing and entity relationship diagram.
Agents discover structure through their tools. This adds ~250 words
that increase cost without improving outcomes.
Suggestion: Remove the entire "Project Structure" section. Extract any
genuinely useful security constraints into a standalone section.
[HIGH] Rule 2: No redundancy with existing docs
Lines affected:
- Project Overview / Key Features — duplicates README.md
- Technology Stack — duplicates README.md
- Development Environment / Starting Services — duplicates README.md
- Testing and Common Framework Commands — discoverable from Makefile
- MCP Database tools listing — agents discover available tools automatically
Problem: Massive duplication with README.md and information agents can
discover on their own.
Suggestion: Remove all of the above. Keep only what's NOT in README
or discoverable.
[HIGH] Rule 3: Minimize requirements ruthlessly
Lines affected: Code Style & Patterns, Architecture Principles with
code examples, Testing Guidelines with code examples (~600 words)
Problem: Standard framework conventions that any LLM already knows:
constructor promotion, attributes over annotations, typed properties,
"no business logic in controllers", "use dependency injection."
Suggestion: Remove all standard patterns. Keep only project-specific
deviations from defaults.
[MEDIUM] Rule 6: No exploration guidance
Lines affected: "Summary for Agents" checklist
Problem: Behavioral guidance that agents handle naturally. Most items
are generic ("keep code simple", "write environment-aware code").
Suggestion: Remove entirely.
[MEDIUM] Rule 7: No generic coding guidelines
Lines affected: Core Principles, Testing Principles
Problem: Universal best practices any LLM knows. "Avoid over-engineering",
"keep code clean", "test public API" add no value.
Suggestion: Remove generic guidelines. Keep only project-specific ones.
[LOW] Rule 9: Keep it short
Problem: At 2,202 words, the file is nearly 3x the recommended target.
Score: 3/10
After it's done, this is what it output as summary
2,202 → 268 words (88% reduction)
What was removed
- Project Overview / Key Features — duplicated README
- Technology Stack — duplicated README
- Development Environment commands — discoverable from makefile
- MCP database tools listing — agents discover available tools automatically
- PHP code style examples (constructor promotion, attributes, typed properties, etc.) — standard PHP 8.x that any LLM knows
- Architecture Principles with code examples (controllers, services, entities) — standard Symfony conventions
- Project Structure directory tree — agents explore via tools
- Entity relationship diagram — discoverable from code
- Common Workflows descriptions — discoverable from code
- Testing Guidelines with code examples — standard PHPUnit
- Environment Variables listing — schema visible in .env
- Summary for Agents checklist — behavioral guidance agents don't need
What was kept (the high-value content)
- Docker-first environment with specific commands
- File access security restrictions
- Multi-tenant isolation rules (the non-obvious security constraint)
- Project-specific conventions that deviate from defaults (no mocking in prod, unidirectional Doctrine, enums over constants)
- Key integration points agents can't easily discover from code alone