tacoda

Agent Harness Structure

Subdirectory CLAUDE.md files provide scoped guidance.

The agent loads only the files relevant to its current working directory.

Directory Layout:

CLAUDE.md ← Root: project overview, architecture, shared rules

├── app/

│ ├── Http/

│ │ ├── Controllers/

tacoda

app/Actions/CLAUDE.md

This is a real harness file from the project.

It tells the agent exactly how to write Action classes.

Actions

Actions encapsulate a single domain operation. They are the primary pattern for complex write operations that go beyond simple CRUD.

When to Use an Action

tacoda

// ─────────────────────────────────────────────────────
// THE INTERIM WRAPPER PATTERN
// Ship SPA features to production inside legacy Blade shells
// ─────────────────────────────────────────────────────

// 1. SPA Component — the source of truth
// resources/js/spa/pages/Dashboard/Dashboard.tsx

import { useEffect, useState } from 'react';
import { AppShell } from '../../layouts/AppShell';

tacoda

<?php

// app/Policies/OrderPolicy.php
// Centralized authorization — one place for all order access rules.

namespace App\Policies;

use App\Order;
use App\User;

tacoda

<?php

// app/Actions/Orders/CreateOrderAction.php
// Single-purpose Action class with Result DTO

namespace App\Actions\Orders;

use App\Order;
use App\Http\Requests\Orders\CreateOrderRequest;
use App\Services\Notifications\Contracts\NotificationInterface;

tacoda

<?php

// BEFORE: Trait mixed into controllers
// ──────────────────────────────────────

trait SlackNotificationTrait
{
    protected function sendSlackNotification(string $channel, string $message): void
    {
        // Directly calls HTTP from inside the controller

tacoda

#!/bin/sh
# .git/hooks/pre-commit
# Runs a fast subset of quality checks before every commit.
# Full checks run in CI — this catches the most common issues early.

set -e

echo "Running pre-commit checks..."

# PHP code style (Pint)

tacoda

# Makefile — Lint and code quality targets
# All commands run inside the Docker app container for consistency.

.PHONY: lint pint pint-fix psalm format format-fix eslint typecheck

## Run all code quality checks (pint + psalm + format + eslint + typecheck)
lint: pint psalm format eslint typecheck

## Check PHP code style (Laravel Pint)
pint:

tacoda

# .github/workflows/ci.yml (simplified excerpt)
# Four-stage pipeline: Build → Quality → Tests → Deploy

name: CI/CD

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

tacoda

<?php

// tests/Setup/UserFactory.php
// Fluent test user factory — accessed via Facades\Tests\Setup\UserFactory

namespace Tests\Setup;

use App\User;
use Database\Seeders\PermissionsSeeder;
use Database\Seeders\RolesSeeder;