Strategy — Follow Framework Conventions

When to use

• The user asks to add a feature inside an existing Laravel, Symfony, or similar framework app and expects it to follow the framework's conventions.
• The user explicitly asks for idiomatic, conventional, or "the framework way" code rather than a custom or hand-rolled approach.
• The task requires deciding where a new controller, migration, command, or service belongs within the framework's directory structure.

When NOT to use

• Do not enforce a convention when the user has explicitly and knowingly asked to bypass it for a documented reason, such as a performance-critical custom path.
• Do not apply this strategy to a plain-PHP script or library that uses no framework, since there are no framework conventions to follow.

Core guidance

• Read configuration through the framework's config layer — Read settings through the framework's configuration and environment layer, not by parsing files or reading environment variables directly in business code.
• Place files in the conventional directory — Put each artifact in the directory the framework expects — controllers in the controllers path, migrations in the migrations path — and follow its naming convention.
• Study existing code before adding a similar file — Before adding a new file of a given kind, read an existing example of the same kind in the project and mirror its structure, base class, and location.
• Resolve dependencies through the framework container — Resolve services through the framework's dependency-injection container rather than instantiating them by hand or reaching for global singletons.
• Use the framework's scaffolding and generators — When the framework ships a generator or scaffold for a concern, use it so the file lands in the conventional place with the conventional shape.

Never

• Never invent a custom directory layout or naming scheme for something the framework already has a convention for, such as controllers, migrations, or service registration.

Prefer

• Prefer the framework's provided abstractions — its router, container, ORM, and config system — over hand-rolled equivalents, and place files where the framework expects them.

Avoid

• Avoid building parallel machinery — a second DI container, a custom autoloader, or a private config loader — that fights or duplicates what the framework already provides.

Escalate to user when

• Escalate to the user when a requirement seems to demand deviating from a core framework convention, and confirm the deviation before committing to it.

Quick recipe

1. Identify the framework's conventional directory for the artifact and open an existing peer of the same kind to copy its shape. (verify: You have named the target directory and an existing example file the new code will mirror.)
2. Use the framework's generator when one exists, otherwise write the file in the conventional location with the conventional base class and wire it through the container and config layer. (verify: The new file sits in the standard path, extends the standard base, and resolves its dependencies through the container rather than by hand.)

Anti-patterns

See references/anti-patterns.md.

Common mistakes

1. Instantiating services by hand instead of resolving them — Constructing framework services with new instead of resolving them from the container loses lifecycle management and test substitution. Fix: Type-hint the dependency and let the container inject it, or resolve it through the container's make or get accessor.
2. Placing files outside the conventional path — Saving a controller or migration outside its conventional directory hides it from the framework's autoloading and discovery. Fix: Move the file into the directory the framework expects and match the naming and namespace of its neighbors.
3. Reading env vars directly instead of the config layer — Calling getenv or reading files directly in business code bypasses the framework's config layer and its caching. Fix: Register the setting in the framework's config files and read it through the config accessor, keeping direct env access to the config layer only.

Version notes

• Convention-following is version-agnostic (PHP >=7.4) — Following the framework's conventions is a strategy that applies to any PHP version; it governs how the agent structures code, not which language features it uses, so it holds from PHP 7.4 upward.

Security

• Not applicable — no I/O, auth, or untrusted input.

Testing

• Activation and decision behavior are verified in eval/scenarios/ai-rules/strategy-framework-conventions.yaml.

Additional resources

• references/anti-patterns.md
• references/examples.md
• references/pitfalls.md
• references/recipes.md
• references/version-differences.md

Knowledge graph

Related: ai-rules/strategy-minimal-diff, laravel/service-container, symfony/dependency-injection