{"slug": "what-is-an-ai-harness-a-practical-guide-with-a-laravel-cms-example", "title": "What Is an AI Harness? A Practical Guide with a Laravel CMS Example", "summary": "An AI harness is a structured set of files, rules, skills, workflows, and project context that surrounds an AI coding agent, providing a consistent way of working across tasks and sessions. Unlike prompting, which tells the agent what to do, a harness tells it how to work, storing persistent engineering knowledge and enabling explicit approval gates. The guide includes a practical example using a Laravel CMS, illustrating how to organize agents, skills, rules, workflows, and context in a project.", "body_md": "An AI harness is a structured set of files, rules, skills, workflows, and project context that surrounds an AI coding agent.\n\nInstead of repeating the same instructions in every prompt, the harness gives the agent a consistent way of working across tasks and sessions.\n\nAnd that's the key idea:\n\nPrompting tells the agent what to do. A harness tells it how to work.\n\nIf you've spent any time pairing with an AI coding agent, you've probably seen the same problems:\n\nSo you keep writing prompts like:\n\n\"Remember to use Policies for authorization.\"\n\n\"Run the tests before you're done.\"\n\n\"Don't modify unrelated files.\"\n\n\"Follow our existing service architecture.\"\n\nThese instructions are valuable.\n\nBut they shouldn't have to live in your prompt every time.\n\nThey should live in the **environment around the agent**.\n\nThat's where an AI harness comes in.\n\nAn AI harness is the structured layer around an AI coding agent that defines:\n\nThe model provides the reasoning.\n\n**The harness provides the discipline.**\n\nThink about a simple task:\n\n\"Add an endpoint for publishing posts.\"\n\nWithout a harness, the process might look like:\n\n```\nUnderstand request\n↓\nExplore project\n↓\nGuess conventions\n↓\nImplement\n↓\nRun some tests\n↓\n\"Done\"\n```\n\nWith a harness:\n\n```\nIdentify task\n↓\nLoad relevant rules\n↓\nLoad project context\n↓\nSelect required skills\n↓\nFollow workflow\n↓\nImplement smallest change\n↓\nValidate\n↓\nTest\n↓\nReview\n↓\nVerify requirement\n↓\nDone\n```\n\nThe difference isn't necessarily a smarter model.\n\nIt's a **more reliable operating environment**.\n\nA prompt is ideal for **task-specific intent**.\n\nA harness is ideal for **persistent engineering knowledge**.\n\n| Plain Prompt | AI Harness |\n|---|---|\n| Instructions rewritten when needed | Instructions persist in the project |\n| Consistency depends on the prompt | Same rules across sessions |\n| Project knowledge gets repeated | Project knowledge is stored |\n| Rules and context are often mixed | Responsibilities are separated |\n| Human decides when it's \"done\" | Definition of Done can be explicit |\n| Safety depends heavily on instructions | Approval gates can be defined |\n| Harder to reuse | Structure can be reused across projects |\n\nFor example, instead of writing this every time:\n\n\"Use Form Requests for validation, Policies for authorization, feature tests for endpoints, don't touch unrelated files, and run\n\n`php artisan test`\n\n.\"\n\nYou can store those decisions once.\n\nThen your actual prompt can remain simple:\n\n\"Add an instant-publish button to the post editor.\"\n\nThe harness supplies the engineering context.\n\nA practical harness can look like this:\n\n```\nai-harness/\n├── AGENTS.md        # Entry point / index\n├── agents/          # WHO acts\n├── skills/          # HOW to handle a concern\n├── rules/           # WHAT must always be true\n├── workflows/       # IN WHAT ORDER to work\n├── context/         # WHAT is true about this project\n└── adapters/        # Tool-specific integration\n```\n\nThese components have different responsibilities.\n\nDefines roles and authority.\n\n```\nagents/\n├── developer.md\n├── reviewer.md\n└── debugger.md\n```\n\nFor example, a Developer may implement changes while a Reviewer focuses on inspecting them.\n\nNot every project needs multiple agents. Start with one if that's enough.\n\nReusable engineering knowledge.\n\n```\nskills/\n├── testing-strategy.md\n├── api-design.md\n├── database-design.md\n└── code-review.md\n```\n\nA testing skill can explain how the project approaches tests, factories, edge cases, and assertions.\n\nRules are constraints.\n\n```\nrules/\n├── core-rules.md\n├── approval-gates.md\n└── definition-of-done.md\n```\n\nExamples:\n\n```\nDo not modify unrelated files.\n\nDo not bypass authorization.\n\nDo not introduce unnecessary dependencies.\n\nDo not declare a task complete without validation.\n\nDestructive operations require human approval.\n```\n\nA workflow defines the sequence for a type of task.\n\nFor example:\n\n```\nworkflows/\n├── feature-development.md\n├── bug-fix.md\n└── release.md\n```\n\nA feature workflow could be:\n\n```\nUnderstand\n↓\nInspect\n↓\nPlan\n↓\nImplement\n↓\nTest\n↓\nReview\n↓\nVerify\n```\n\nContext contains project-specific facts.\n\n```\ncontext/\n├── project.md\n├── architecture.md\n├── domain.md\n└── conventions.md\n```\n\nFor example:\n\n```\nproject.md\n→ Laravel 11\n→ PHP 8.3\n→ MySQL\n→ Redis\n\narchitecture.md\n→ Form Requests\n→ Policies\n→ Services\n→ Feature Tests\n```\n\nThis is the part that changes most from project to project.\n\nOne instruction can actually contain four different concepts.\n\nTake:\n\n\"Always run tests before finishing.\"\n\nIt can become:\n\n`php artisan test`\n\n.This separation is important.\n\nIt prevents one giant instruction file from becoming the place where everything lives.\n\nImagine a Laravel CMS with:\n\nThe repository could look like:\n\n```\nlaravel-cms/\n├── AGENTS.md\n├── ai-harness/\n│   ├── AGENTS.md\n│   ├── agents/\n│   ├── skills/\n│   ├── rules/\n│   │   ├── core-rules.md\n│   │   ├── approval-gates.md\n│   │   └── definition-of-done.md\n│   ├── workflows/\n│   ├── context/\n│   │   ├── project.md\n│   │   ├── architecture.md\n│   │   ├── domain.md\n│   │   └── conventions.md\n│   └── adapters/\n├── app/\n├── database/\n├── tests/\n└── ...\n```\n\nNow imagine the task is:\n\n\"Add an instant-publish button for a post from the admin panel.\"\n\nThe harness can guide the agent through:\n\n```\nTask arrives\n↓\nIdentify task type\n↓\nFeature Development workflow\n↓\nLoad core Rules\n↓\nLoad relevant Context\n↓\nSelect required Skills\n↓\nCheck Approval Gates\n↓\nImplement smallest possible change\n↓\nRun validation\n↓\nRun tests\n↓\nReview changes\n↓\nVerify original requirement\n↓\nDone\n```\n\nNotice that the agent doesn't necessarily need every project document.\n\nA good harness can instruct it to load **only the context relevant to the task**.\n\nFor this feature, that might mean:\n\n```\nproject.md       ✓\narchitecture.md  ✓\ndomain.md        ✓\nconventions.md   ✓\npayments.md      ✗\n```\n\nThe exact loading behavior depends on the coding tool, but the harness should make the intended boundaries explicit.\n\nOne of the biggest benefits of a harness is defining what \"done\" actually means.\n\nCreating the button isn't enough.\n\nThe agent should verify:\n\n```\n✓ Button exists\n✓ Correct users can access it\n✓ Authorization is enforced\n✓ Post becomes published\n✓ Invalid states are handled\n✓ Relevant tests pass\n✓ No unrelated files were changed\n✓ Original requirement is satisfied\n```\n\nThat's what a:\n\n```\nrules/definition-of-done.md\n```\n\ncan establish.\n\nThe goal is simple:\n\n\"Code exists\" ≠ \"Task is complete.\"\n\nSome operations are routine.\n\nOthers are risky.\n\nImagine the agent receives:\n\n\"Delete this category and all its posts.\"\n\nThat's potentially destructive.\n\nThe harness can define an approval gate:\n\n```\nPotentially destructive operation\n↓\nExplain impact\n↓\nStop\n↓\nRequest human approval\n↓\nContinue only after approval\n```\n\nThis is an important distinction:\n\n**A good agent shouldn't only know how to continue. It should also know when to stop.**\n\nWhether a particular tool can technically enforce every gate depends on the tool, but the policy itself belongs in the harness.\n\nThe harness should remain **tool-agnostic**.\n\nYour engineering rules shouldn't need to change because you switched from Codex to Cursor.\n\nOnly the entry point changes.\n\nConceptually:\n\n```\n                 Shared AI Harness\n                        │\n             ┌──────────┴──────────┐\n             │                     │\n           Codex                 Cursor\n             │                     │\n        AGENTS.md            .cursor/rules/\n```\n\nFor Codex, keep the repository-level `AGENTS.md`\n\nthin:\n\n```\n## Laravel CMS — Agent Entry Point\n\nBefore performing engineering work in this repository,\nread and follow `ai-harness/AGENTS.md`.\n\nThe harness defines the project's:\n- Agents\n- Skills\n- Rules\n- Workflows\n- Context\n\nDo not duplicate the harness content here.\n```\n\nFor Cursor, use its project rules under:\n\n```\n.cursor/\n└── rules/\n    └── harness.mdc\n```\n\nThat rule can simply point the agent toward the shared harness.\n\nThe principle is:\n\nOne source of truth. Thin tool adapters.\n\nDon't copy your entire engineering system into both `AGENTS.md`\n\nand Cursor rules.\n\nWhen you're unsure where an instruction belongs, ask:\n\n| Question | Put it in |\n|---|---|\n| \"This must always be true.\" | `rules/` |\n| \"This is how we do this.\" | `skills/` |\n| \"These steps must happen in this order.\" | `workflows/` |\n| \"This is true about this project.\" | `context/` |\n| \"This role has specific authority.\" | `agents/` |\n| \"This is how Cursor/Codex connects.\" |\n`adapters/` / entry point |\n\nThis simple distinction prevents the harness from becoming another giant instruction dump.\n\nYou don't need a huge framework on day one.\n\nA useful starting point could be:\n\n```\nai-harness/\n├── AGENTS.md\n├── rules/\n│   ├── core-rules.md\n│   └── definition-of-done.md\n├── workflows/\n│   ├── feature-development.md\n│   └── bug-fix.md\n├── skills/\n│   └── testing-strategy.md\n└── context/\n    ├── project.md\n    └── architecture.md\n```\n\nThen grow it when you notice repetition.\n\nIf you keep explaining the same thing to the agent, **that's a signal that the knowledge probably belongs in the harness.**\n\nAn AI harness isn't just a bigger prompt.\n\nIt's a structured engineering environment that gives an AI coding agent:\n\nThe goal isn't to make the model smarter.\n\nIt's to make the model **more predictable and reliable inside your project**.\n\nThe strongest principle is:\n\nDon't put more instructions in the prompt. Put persistent engineering knowledge in the environment around the agent.\n\nPrompting tells the agent **what you want**.\n\nHarness engineering tells it **how to work**.\n\nAnd that's the real shift:\n\nFrom prompting an AI to engineering the environment in which the AI works.", "url": "https://wpnews.pro/news/what-is-an-ai-harness-a-practical-guide-with-a-laravel-cms-example", "canonical_source": "https://dev.to/yasserelgammal/what-is-an-ai-harness-a-practical-guide-with-a-laravel-cms-example-3d4g", "published_at": "2026-09-03 22:03:42+00:00", "updated_at": "2026-09-03 22:24:35.275183+00:00", "lang": "en", "topics": ["ai-agents", "developer-tools", "ai-tools"], "entities": ["Laravel"], "alternates": {"html": "https://wpnews.pro/news/what-is-an-ai-harness-a-practical-guide-with-a-laravel-cms-example", "markdown": "https://wpnews.pro/news/what-is-an-ai-harness-a-practical-guide-with-a-laravel-cms-example.md", "text": "https://wpnews.pro/news/what-is-an-ai-harness-a-practical-guide-with-a-laravel-cms-example.txt", "jsonld": "https://wpnews.pro/news/what-is-an-ai-harness-a-practical-guide-with-a-laravel-cms-example.jsonld"}}