{"slug": "stop-ai-from-writing-sloppy-laravel-code-my-kilo-code-agents-md-workflow", "title": "Stop AI From Writing Sloppy Laravel Code: My Kilo Code + AGENTS.md Workflow", "summary": "A developer has published a workflow for constraining AI coding assistants to an existing Laravel project's architecture using an AGENTS.md rules file, a skills.md knowledge file, and the Kilo Code agent, rather than prompting the AI to \"write better code.\" The approach requires the agent to inspect the existing project first — checking composer.json and current framework choices such as Livewire, Inertia, Tailwind or existing components — so it extends rather than redesigns the codebase, and the author notes the same pattern maps to OpenCode, Codex and Claude Code via their respective instruction files.", "body_md": "AI coding assistants are getting very good at generating Laravel code.\n\nGive an AI a feature request and it can probably create:\n\nThe problem is not whether the code works.\n\nThe problem is whether the code **belongs in the project**.\n\nAI can easily generate Laravel code that works today but becomes a maintenance problem tomorrow:\n\n`$request->all()``<style>` blocks`<script>` blocks\nFor me, the solution is not to tell the AI to \"write better code\".\n\nThe better approach is to **define the engineering rules and make the AI work inside the existing project architecture**.\n\nMy current workflow is built around:\n\n```\nLaravel Project\n      │\n      ├── AGENTS.md\n      │      └── Engineering rules\n      │\n      ├── skills.md\n      │      └── Knowledge / examples / procedures\n      │\n      └── Kilo Code\n             └── Implement within those rules\n```\n\nAnd for longer-running projects, there is another layer that can work alongside them:\n\n```\nDSOM Brain\n└── Project state, decisions, continuity and context\n```\n\nI'll come back to that near the end.\n\nBefore asking an AI coding agent to implement anything, I want it to understand the project that already exists.\n\nThis is probably the most important rule in my workflow.\n\nDon't start with:\n\n\"Build a user management system.\"\n\nStart with:\n\n\"Inspect the existing project first.\"\n\nThe AI should inspect things such as:\n\n`composer.json`\nThe reason is simple.\n\n**The existing project is already an architecture.**\n\nIf the application already uses Livewire, don't suddenly introduce Inertia and React just because the AI knows how to generate them.\n\nIf the application already uses React + Inertia, don't create a random Blade-based application UI.\n\nIf the application uses Tailwind, don't introduce Bootstrap.\n\nIf the project already has reusable components, don't create another component that does the same thing.\n\nAI should extend the project, not accidentally redesign it.\n\nAI optimizes heavily for producing a plausible solution.\n\nThat doesn't necessarily mean it optimizes for:\n\nFor example, imagine this request:\n\nAdd an endpoint to update a user's profile.\n\nA simplistic AI implementation might put everything inside the controller:\n\n``` php\npublic function update(Request $request, User $user)\n{\n    $user->update($request->all());\n\n    // validation\n    // authorization\n    // business logic\n    // logging\n    // notifications\n    // other operations...\n\n    return redirect()->back();\n}\n```\n\nIt might work.\n\nBut the better Laravel implementation should consider:\n\nThe goal isn't to make the code more complicated.\n\nThe goal is to put each responsibility where it belongs.\n\nAlthough this workflow was developed and tested with Kilo Code, the underlying idea is not tied to Kilo Code.\n\nThe important part is not the tool name. The important part is giving an AI coding agent a clear set of engineering rules, project knowledge, and working context before asking it to write code.\n\nIf you use other coding agents such as OpenCode, Codex, or Claude Code, you can apply the same concept.\n\nThe exact mechanism may be different:\n\nthe instruction file may have a different name,\n\nthe location may be different,\n\nthe way instructions are loaded may be different,\n\nand each tool may have its own instruction hierarchy or configuration.\n\nBut the architecture can remain the same:\n\n```\n                AI Coding Agent\n                       │\n          ┌────────────┼────────────┐\n          ▼            ▼            ▼\n    Engineering     Project      Working\n       Rules       Knowledge      Context\n          │            │            │\n          └────────────┼────────────┘\n                       ▼\n                Laravel Project\n```\n\nFor example, the same principles can be adapted to:\n\nKilo Code    → AGENTS.md + skills\n\nOpenCode     → project instructions / AGENTS.md\n\nCodex        → project instructions / AGENTS.md\n\nClaude Code  → project instructions / CLAUDE.md\n\nThe exact filenames and supported features should be checked against the documentation for the coding agent you are using.\n\nThe key idea\n\nDon't think:\n\n\"I need to use Kilo Code because this workflow uses AGENTS.md.\"\n\nThink instead:\n\n\"I need to give my coding agent an engineering contract.\"\n\nThat contract should tell the agent things such as:\n\nhow the project is structured,\n\nwhich Laravel conventions to follow,\n\nhow authorization should be handled,\n\nwhere validation belongs,\n\nhow database access should be designed,\n\nwhat security practices are required,\n\nhow tests should be written,\n\nwhat the agent must inspect before changing code,\n\nand what it should not change unnecessarily.\n\nSo if you move from Kilo Code to OpenCode, Codex, or Claude Code, you don't have to throw away the workflow.\n\nYou adapt the instruction layer, while keeping the underlying engineering principles.\n\nThis makes the workflow tool-agnostic, even though my current implementation and examples are based on Kilo Code.\n\n`AGENTS.md` as the Project Engineering Contract\nThis is where `AGENTS.md` becomes useful.\n\nInstead of repeating the same instructions every time I ask the AI to implement something, I keep the important engineering rules inside the repository.\n\nFor example:\n\n```\nmy-laravel-app/\n├── AGENTS.md\n├── skills.md\n├── composer.json\n├── artisan\n├── app/\n├── bootstrap/\n├── config/\n├── database/\n├── public/\n├── resources/\n├── routes/\n├── storage/\n└── tests/\n```\n\nThe important idea is that `AGENTS.md` is not documentation for humans only.\n\nIt becomes a **working contract between the project and the AI coding agent**.\n\n```\n# Laravel Engineering Rules\n\n- Follow the existing project architecture.\n- Inspect existing code before implementation.\n- Keep controllers thin.\n- Use Form Requests for validation.\n- Use policies for authorization.\n- Prefer Eloquent over unnecessary repository abstractions.\n- Do not put business logic in Blade.\n- Avoid N+1 queries.\n- Use migrations for database changes.\n- Write tests for application behaviour.\n- Do not introduce another frontend framework without a clear requirement.\n- Reuse existing components.\n- Do not add unnecessary abstractions.\n- Do not refactor unrelated code.\n```\n\nNow the AI has something concrete to follow.\n\nLaravel applications don't all have the same frontend architecture.\n\nA project may use:\n\nLaravel's current starter kits also provide different application stacks, so the starter kit already present in a project should be treated as part of that project's architecture.\n\nMy rule is:\n\n**Inspect the starter kit before creating new UI.**\n\nIf the project already has a component system, use it.\n\nIf the project already has layouts, use them.\n\nIf the project already has navigation components, don't create another navigation implementation.\n\nThe starter kit is a starting architecture, not something the AI should casually replace.\n\nThis is one of the easiest ways for AI-generated code to become messy.\n\nImagine an existing Laravel project using:\n\n```\nBlade + Alpine + Tailwind\n```\n\nThen an AI decides to add:\n\n```\nReact + Vite + another component library\n```\n\nNow the project has two frontend architectures.\n\nThat might be justified in some applications.\n\nBut it should never happen simply because the AI generated a React solution faster.\n\nThe rule should be:\n\nFollow the frontend architecture already used by the project unless there is an explicit reason to change it.\n\nBefore creating a new component, look for an existing one.\n\n```\nresources/views/components/\n```\n\nmight already contain:\n\n```\nbutton.blade.php\ninput.blade.php\nmodal.blade.php\nalert.blade.php\ntable.blade.php\n```\n\nIf the application already has a button component, don't generate another button implementation.\n\nThe AI should inspect first.\n\nThis simple rule prevents a lot of duplication.\n\nAnother common AI-generated pattern is:\n\n```\n<style>\n    .some-big-component {\n        ...\n    }\n\n    .another-component {\n        ...\n    }\n\n    /* 200 more lines */\n</style>\n```\n\nThis may work, but it can quickly become difficult to maintain.\n\nIf the project uses Tailwind, use Tailwind.\n\nIf the project uses Bootstrap, use Bootstrap.\n\nIf custom CSS is genuinely required, put it into the project's existing CSS structure.\n\n```\nresources/\n└── css/\n    ├── app.css\n    └── components/\n        └── editor.css\n```\n\nThe exact structure depends on the project.\n\nThe important rule is:\n\n**Follow the project's existing CSS architecture instead of dumping large amounts of CSS into Blade.**\n\nThe same principle applies to JavaScript.\n\nDon't create a huge:\n\n```\n<script>\n    // 300 lines of application logic\n</script>\n```\n\ninside a Blade view if the project already has a proper JavaScript/TypeScript structure.\n\nThese are the rules I want an AI coding agent to understand before it starts changing my Laravel application.\n\nControllers should coordinate the request.\n\nThey shouldn't become the entire application.\n\nBad:\n\n```\npublic function store(Request $request)\n{\n    // validation\n\n    // authorization\n\n    // database queries\n\n    // business rules\n\n    // notifications\n\n    // logging\n\n    // calculations\n\n    // 100 more lines\n}\n```\n\nBetter:\n\n``` php\npublic function store(StoreOrderRequest $request)\n{\n    $this->authorize('create', Order::class);\n\n    $order = $this->orderService->create(\n        $request->validated()\n    );\n\n    return redirect()->route('orders.show', $order);\n}\n```\n\nThe exact architecture depends on the project.\n\nThe important part is keeping responsibilities separated.\n\nI don't want AI-generated Laravel code to casually do this:\n\n``` php\n$data = $request->all();\n```\n\nEspecially when the data is going into a model.\n\nUse a Form Request when validation and authorization belong there:\n\n``` php\n$data = $request->validated();\n```\n\nOr:\n\n``` php\n$data = $request->safe()->only([\n    'name',\n    'email',\n]);\n```\n\nThis makes the input boundary explicit.\n\nIt also reduces the chance of accidentally passing unexpected fields into application logic.\n\nAnother common mistake is confusing:\n\n```\nWho are you?\n```\n\nwith:\n\n```\nAre you allowed to do this?\n```\n\nAuthentication identifies the user.\n\nAuthorization determines whether that user can perform the operation.\n\nLaravel provides policies and gates for this.\n\n``` php\n$this->authorize('update', $post);\n```\n\nThe AI should not assume that:\n\n``` php\nauth()->check()\n```\n\nmeans the user is allowed to modify the resource.\n\nLaravel already provides a powerful ORM.\n\nI don't want an AI to create:\n\n```\nRepository\n    ↓\nInterface\n    ↓\nRepository Implementation\n    ↓\nManager\n    ↓\nService\n    ↓\nModel\n```\n\nfor a simple CRUD operation.\n\nIf Eloquent is enough:\n\n``` php\n$user = User::findOrFail($id);\n```\n\nuse Eloquent.\n\nRepositories can be useful in the right context.\n\nBut abstraction should solve a problem, not create one.\n\nAI-generated Laravel code can easily create N+1 queries.\n\n``` php\n$posts = Post::all();\n\nforeach ($posts as $post) {\n    echo $post->author->name;\n}\n```\n\nThe correct implementation may need:\n\n``` php\n$posts = Post::with('author')->get();\n```\n\nThe AI should inspect relationships and query behaviour rather than assuming that syntactically valid Eloquent code is automatically efficient.\n\nBlade should primarily handle presentation.\n\nI don't want this:\n\n``` php\n@php\n    $orders = Order::where('user_id', auth()->id())->get();\n\n    // business logic\n    // calculations\n    // database operations\n@endphp\n```\n\nThe view should receive the data it needs.\n\n``` php\n$orders = $user->orders()->latest()->get();\n\nreturn view('orders.index', compact('orders'));\n```\n\nThen Blade renders it.\n\nI'm not against service classes.\n\nI'm against creating them automatically.\n\nA service or action can make sense when there is:\n\nBut this:\n\n```\nCreateUserService\n```\n\nfor a three-line CRUD operation may simply add another layer.\n\nThe rule is:\n\n**Introduce abstractions because the problem requires them, not because AI likes generating classes.**\n\nDon't manually modify production database structures.\n\nUse migrations.\n\n```\nphp artisan make:migration add_status_to_orders_table\n```\n\nThen define the change.\n\nDatabase design should also consider:\n\nAI should inspect the existing schema before creating another migration.\n\nIf an operation modifies several related records and they must succeed or fail together, consider a transaction.\n\n```\nDB::transaction(function () {\n    // create order\n\n    // create order items\n\n    // update inventory\n});\n```\n\nBut again, don't wrap every single database query inside a transaction just because the AI knows the API exists.\n\nUse transactions when atomicity matters.\n\nSecurity shouldn't be an afterthought.\n\nFor Laravel development, I want the AI to consider:\n\n``` php\nLog::info('User updated profile', [\n    'user_id' => $user->id,\n]);\n```\n\nis useful.\n\nBut:\n\n``` php\nLog::info($request->all());\n```\n\ncould expose sensitive information.\n\nThe AI should understand that logging itself can become a security problem.\n\nI don't want AI to say:\n\nTests should be added later.\n\nIf a feature changes application behaviour, testing should be part of the implementation.\n\n```\nFeature\n├── implementation\n├── validation\n├── authorization\n└── tests\n```\n\nFeature tests are useful for application behaviour.\n\nUnit tests are useful for isolated logic.\n\nAnd one important rule:\n\nNever claim that tests passed unless they were actually executed.\n\nAn AI saying:\n\n```\nAll tests pass.\n```\n\nwithout running them is not useful.\n\nBefore accepting AI-generated code, I can ask:\n\n```\n- Did you inspect the existing architecture first?\n- Did you follow the existing starter kit?\n- Did you reuse existing components?\n- Did you follow the existing CSS/JS structure?\n- Are controllers still thin?\n- Is validation handled properly?\n- Is authorization handled separately?\n- Did you use Eloquent before introducing abstractions?\n- Did you check for N+1 queries?\n- Is business logic outside Blade?\n- Are services/actions actually justified?\n- Are database changes done through migrations?\n- Are transactions used only where needed?\n- Did you consider security?\n- Did you add appropriate tests?\n- Did you avoid unrelated refactoring?\n- Did you remove debug code?\n```\n\nThis checklist is often more valuable than telling an AI:\n\n\"Write clean code.\"\n\nBecause \"clean\" is subjective.\n\nRules are more explicit.\n\n`skills.md` Is Different From I also like separating **rules** from **knowledge**.\n\n`AGENTS.md` answers:\n\n**How should the AI work on this project?**\n\nWhile `skills.md` can contain:\n\n```\nAGENTS.md\n└── Rules\n\nskills.md\n└── Knowledge / procedures / examples\n```\n\nThis keeps the main engineering contract focused.\n\nThe AI doesn't need every piece of project knowledge to become a hard rule.\n\nMy current workflow uses **Kilo Code** as the coding agent.\n\nI don't need to run four different coding agents for every Laravel project.\n\nThe important part isn't how many AI tools are involved.\n\nThe important part is whether the AI is working inside a clear engineering environment.\n\nMy basic setup is:\n\n```\nKilo Code\n    │\n    ├── Inspect project\n    │\n    ├── Read AGENTS.md\n    │\n    ├── Load relevant skills\n    │\n    ├── Plan\n    │\n    ├── Implement\n    │\n    ├── Test\n    │\n    └── Review changes\n```\n\nAnother developer may prefer another coding agent.\n\nThat's fine.\n\nThe principles remain the same.\n\nMy development environment is not necessarily a traditional Linux workstation.\n\nI work across:\n\n```\nWindows\n   │\n   └── WSL2\n          │\n          ├── Linux\n          ├── Laravel\n          ├── Git\n          └── Kilo Code\n```\n\nThis is another reason why project-local instructions are useful.\n\nThe AI shouldn't assume a generic environment.\n\nIf the project has specific commands, paths, services or development procedures, document them.\n\n`AGENTS.md` belongs in the project.\n\nThat means it may eventually be committed to Git.\n\nTherefore:\n\n**Don't put secrets inside it.**\n\nNever store:\n\n```\nAPI keys\npasswords\ntokens\nprivate credentials\nproduction secrets\n```\n\nInstead document the expected configuration:\n\n```\nMAIL_USERNAME=<configured through environment>\nMAIL_PASSWORD=<configured through environment>\n```\n\nThe actual secret belongs in the appropriate secret/configuration mechanism.\n\nA simple Laravel project can look like:\n\n```\nmy-laravel-app/\n├── AGENTS.md\n├── skills.md\n├── composer.json\n├── artisan\n├── app/\n├── bootstrap/\n├── config/\n├── database/\n├── public/\n├── resources/\n├── routes/\n├── storage/\n└── tests/\n```\n\nThe important part isn't the number of files.\n\nIt is that the project contains a small, visible place where the AI can learn:\n\n```\nRules\nKnowledge\nCode\nTests\n```\n\nThis is where another interesting layer comes in.\n\n`AGENTS.md` is useful for defining **how the AI should work**.\n\n`skills.md` is useful for giving the AI **knowledge, procedures and examples**.\n\nBut long-running projects can have another problem:\n\n**What does the AI need to remember about the project over time?**\n\nArchitecture decisions.\n\nPrevious work.\n\nCurrent project state.\n\nSession handovers.\n\nDecisions that were already made.\n\nThings that should not be repeated.\n\nThis is a different problem from coding rules.\n\nOne project I came across is **Deep State of Mind (DSOM)**, which approaches this problem as a persistent AI context and governance layer. Its DSOM architecture includes persistent project state, decision/context artifacts, session continuity and a Git-oriented workflow.\n\nConceptually, I see the layers like this:\n\n```\n                    AI Coding Workflow\n                           │\n          ┌────────────────┼────────────────┐\n          │                │                │\n          ▼                ▼                ▼\n     AGENTS.md         skills.md        DSOM Brain\n          │                │                │\n       Rules          Knowledge       Project State\n     & standards       & examples     & continuity\n          │                │                │\n          └────────────────┼────────────────┘\n                           │\n                           ▼\n                       Kilo Code\n                           │\n                           ▼\n                    Laravel Project\n```\n\nThe distinction is important:\n\n```\nAGENTS.md\n\"What rules should the AI follow?\"\n\nskills.md\n\"What knowledge/procedures can help the AI?\"\n\nDSOM Brain\n\"What does the AI need to remember about this project?\"\n```\n\nI don't see DSOM Brain as something that replaces `AGENTS.md` or `skills.md`.\n\nInstead, it can **run alongside them**.\n\nFor a small Laravel project, `AGENTS.md` and a small set of skills may already be enough.\n\nFor a long-running project, however, persistent project state and context can become useful.\n\nThat's where **DSOM Brain** becomes interesting.\n\nI'm keeping the DSOM Brain implementation out of this article because it deserves its own discussion.\n\nI'll cover that separately in another article.\n\nFor reference:\n\n[Deep State of Mind (DSOM) For My AI](https://linuxmalaysia.github.io/deep-state-of-mind-for-my-ai/?utm_source=chatgpt.com)\n\nThe goal isn't to make AI write more code.\n\nThe goal is to make AI work **inside an engineering system**.\n\nMy current thinking is:\n\n```\nAGENTS.md\n    │\n    └── Engineering rules\n\nskills.md\n    │\n    └── Knowledge and procedures\n\nDSOM Brain\n    │\n    └── Persistent project context\n\nKilo Code\n    │\n    └── Implementation\n\nGit\n    │\n    └── History and audit trail\n\nLaravel\n    │\n    └── The actual application\n```\n\nThis changes the relationship with an AI coding agent.\n\nInstead of:\n\n\"AI, build this feature.\"\n\nThe workflow becomes:\n\n\"Here is the project. Inspect it first. Here are the engineering rules. Here are the relevant skills. Here is the project context. Now implement the feature within the existing architecture.\"\n\nThat is a much more useful way for me to think about AI-assisted Laravel development.\n\n**Don't try to teach the AI everything. Define the rules that matter, inspect the existing project first, keep those rules close to the project, and make the AI work within the architecture that already exists.**", "url": "https://wpnews.pro/news/stop-ai-from-writing-sloppy-laravel-code-my-kilo-code-agents-md-workflow", "canonical_source": "https://dev.to/hardyweb/stop-ai-from-writing-sloppy-laravel-code-my-kilo-code-agentsmd-workflow-3556", "published_at": "2026-09-25 12:41:29+00:00", "updated_at": "2026-09-25 13:01:40.164024+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "developer-tools", "ai-products"], "entities": ["Laravel", "Kilo Code", "OpenCode", "Codex", "Claude Code", "Livewire", "Inertia"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/stop-ai-from-writing-sloppy-laravel-code-my-kilo-code-agents-md-workflow", "markdown": "https://wpnews.pro/news/stop-ai-from-writing-sloppy-laravel-code-my-kilo-code-agents-md-workflow.md", "text": "https://wpnews.pro/news/stop-ai-from-writing-sloppy-laravel-code-my-kilo-code-agents-md-workflow.txt", "jsonld": "https://wpnews.pro/news/stop-ai-from-writing-sloppy-laravel-code-my-kilo-code-agents-md-workflow.jsonld"}}