harness-structure

HarnessStructure.md

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/
│   │   │   ├── Api/CLAUDE.md            ← API controller patterns (growth direction)
│   │   │   └── Web/CLAUDE.md            ← Legacy controllers (bug fixes only)
│   │   └── Resources/CLAUDE.md          ← API Resource conventions
│   ├── Actions/CLAUDE.md                ← Action pattern, Result DTOs
│   ├── Services/CLAUDE.md               ← Contract-first design, strategy pattern
│   └── Policies/CLAUDE.md               ← Authorization patterns
├── database/
│   └── migrations/CLAUDE.md             ← Migration naming, column types
├── tests/CLAUDE.md                      ← Test patterns, UserFactory, TDD
└── resources/
    └── js/spa/CLAUDE.md                 ← SPA architecture, Interim wrappers

Harness Table Excerpt (from root CLAUDE.md)

Subdirectory CLAUDE.md files provide detailed patterns and constraints for each layer of the codebase. Read the relevant file before working in that area.

Area	Harness File	Summary
API Controllers	app/Http/Controllers/Api/CLAUDE.md	QueryBuilder, Resources, thin controllers
Web Controllers	app/Http/Controllers/Web/CLAUDE.md	Legacy. Bug fixes only, no new features.
React SPA	resources/js/spa/CLAUDE.md	SPA source of truth; Interim wrappers
Services	app/Services/CLAUDE.md	Contract-first, strategy pattern
Actions	app/Actions/CLAUDE.md	Single execute(), Result DTOs
Tests	tests/CLAUDE.md	UserFactory, ApiTestCase, TDD workflow
API Resources	app/Http/Resources/CLAUDE.md	allowedIncludes(), casting conventions
Policies	app/Policies/CLAUDE.md	Role helpers, scoping patterns
Migrations	database/migrations/CLAUDE.md	Naming, nullability, soft deletes

When building a new feature, the typical flow touches these harness files:

1. Migrations — schema changes
2. Actions/Services — business logic
3. API Controllers + Resources — expose via API
4. SPA — React page, API client, types
5. Tests — PHP and JS tests throughout (TDD)

Pre-Commit Verification (from root CLAUDE.md)

Before a change can be committed, complete these steps in order:

1. Code quality: make lint — all checks must pass
2. PHP tests: make test — all PHPUnit tests must pass
3. JS tests: make test-js — all Vitest tests must pass
4. Browser verification (UI changes only): Puppeteer MCP
5. E2E tests: Ask before running. If approved, make e2e.

Fix any failures before proceeding to the next step.

Feedback Protocol (from root CLAUDE.md)

All feedback about code quality, patterns, or practices follows this loop:

1. Update the appropriate CLAUDE.md harness file to capture the pattern
2. Reload that harness file into context
3. Re-attempt the change using the updated guidance

This ensures the harness evolves with every review and the team benefits from accumulated decisions.