Backend Ai Rules Laravel Package

Getting Started

This package is not a runtime library — it ships markdown rule files that encode backend conventions so AI coding assistants (Cursor, Windsurf, Copilot, Claude Code, etc.) generate code that matches your team's style. Treat it like a linting config for your AI pair programmer, not like a Composer dependency you call at runtime.

Minimal steps:

1. Pull it in as a dev-only dependency (or a git submodule / plain clone — see patterns below):

   composer require --dev hypecode/backend-ai-rules
   

2. Open the repo root and read the rule files before wiring anything up. Skim each file's front-matter/header to see which concern it covers (architecture, testing, naming, API design, and — as of 0.4.0 — OpenAPI).
3. Wire the rules into your assistant's expected location. Typical targets:
   • .cursor/rules/*.mdc (Cursor)
   • .windsurfrules or .windsurf/rules/ (Windsurf)
   • .github/copilot-instructions.md (Copilot)
   • CLAUDE.md / AGENTS.md (Claude Code, Codex-style agents)
4. First use case: pick one rule file that matches a pain point you already have — e.g. the controller/FormRequest conventions — and ask the assistant to scaffold a new endpoint. Compare the output to what you'd normally write by hand. If it's close, expand to more rule files.

If you're here specifically for the 0.4.0 OpenAPI addition, start with that file and the API-related rules together; they're designed to be read as a set when generating or reviewing specs.

Implementation Patterns

Vendor the rules, don't symlink them. Because assistants read files from the working tree, the most reliable pattern is to copy the relevant rule files into your project's assistant directory and commit them. Symlinks work on macOS/Linux but break for Windows contributors and in some CI containers.

Layer, don't replace. Keep the package rules as a "base" and add a thin project-specific overlay (project-conventions.mdc, AGENTS.md, etc.) for things unique to your app — domain naming, package choices, queue conventions. When the package releases a new rule file (like openAPI in 0.4.0), you drop it in and your overlay still applies.

Separate "always-on" from "scoped" rules. Most assistants support glob-scoped rules. Put architecture/naming rules in always-on, and scope API/OpenAPI rules to app/Http/**, routes/**, and your spec directory so they don't burn context on unrelated edits.

Code review prompts. Beyond scaffolding, feed the rules into review prompts: "Review this diff against the rules in .cursor/rules/. Flag violations with file:line." This is often higher value than generation, because it catches drift on PRs you'd otherwise rubber-stamp.

OpenAPI workflow (new in 0.4.0). Two viable directions:

• Spec-first: ask the assistant to draft/refine the OpenAPI document using the rule file, then generate controllers/FormRequests against it.
• Code-first: point the assistant at routes/api.php plus your Resources/FormRequests and have it emit or update the spec, then validate.

Either way, keep the spec in the repo and gate it in CI:

npx @redocly/cli lint openapi.yaml
# or
npx spectral lint openapi.yaml

Pin the version and bump deliberately. Because rules silently change model behaviour, treat a bump like a linter upgrade: read the diff, re-run a couple of representative prompts, and check the output still matches your conventions before merging.

Share across repos. For a multi-repo org, keep the canonical copy in one place and copy it out via a small script or a make sync-ai-rules target so every service gets the same baseline.

Gotchas and Tips

• Rules are context budget. Every always-on file costs tokens on every request. Ten rule files of 300 lines each will crowd out the actual code the model needs. Scope aggressively and keep files short and imperative.
• Assistant-specific filenames are a trap. Cursor won't read CLAUDE.md; Copilot won't read .cursor/rules. Generate the per-assistant variants from one source of truth rather than hand-maintaining four copies that drift.
• Silent ignoring. If the assistant seems to ignore a rule, check (a) the filename/location matches what that tool expects, (b) front-matter globs/alwaysApply is correct, and (c) the file wasn't truncated by context limits. This is the single most common "the rules don't work" report.
• Framework drift. Rules written against an older Laravel version will happily produce outdated idioms (e.g. removed helpers, old validation syntax). Re-read them after major framework upgrades rather than trusting them blindly.
• OpenAPI hallucination is real. Expect the model to invent schemas, mislabel required fields, and confuse OpenAPI 3.0 vs 3.1 (notably nullable vs type: [string, "null"]). Always lint the output and pin the spec version explicitly in the prompt. Add example values — they measurably reduce nonsense.
• Don't edit files in vendor/. Your changes vanish on composer update. Copy into your own directory (or a submodule) and customise there; upstream new rules then merge cleanly.
• Extension points. The practical extension surface is: your project overlay file, assistant-specific scoping/globs, and CI validation scripts. There's no plugin API to hook into — treat the rules as text you own once vendored.
• CI hygiene. If you commit AI rules, add a check that the vendored copy matches the pinned version (a checksum or a composer.lock-aware script) so contributors don't accidentally fork conventions in their working tree.