harness-init

name

harness-init

description

One-time codebase initialization for harness engineering with Claude agents. Analyzes the existing codebase and scaffolds an agent-legible knowledge base (docs/, ARCHITECTURE.md, lean CLAUDE.md as table of contents), architectural boundary enforcement (dependency direction linters, file size limits, structured logging checks, naming conventions), quality scoring, execution plans, and Claude Code agent workflows (custom commands, hooks, doc-gardening). Use this skill when the user wants to adopt harness engineering, make their codebase agent-legible, set up agent-first development infrastructure, or mentions 'harness engineering'. Also trigger when someone asks about organizing their repo for AI agents, setting up Claude agent workflows, or making a codebase machine-navigable. Targets teams already using Claude Code heavily.

Harness Engineering Initialization

Transform an existing codebase into a harness-engineered environment optimized for Claude agents. This implements the core insight from harness engineering: humans steer, agents execute — and the codebase is the single source of truth.

The repository becomes a self-describing system. Everything an agent needs to reason about the code lives in-repo, versioned, cross-linked, and mechanically enforced. If it's not in the repo, it doesn't exist for agents.

What Gets Created

1. Lean CLAUDE.md (~100 lines) — table of contents with progressive disclosure, not an encyclopedia
2. ARCHITECTURE.md — system map derived from actual codebase analysis
3. Structured docs/ — design docs, exec plans, product specs, quality scores, golden principles, enforcement rules
4. Enforcement scripts — dependency direction validation, file size limits, structured logging, naming conventions, doc freshness checks — all with agent-friendly remediation messages
5. Claude Code commands — /doc-garden, /quality-check, /arch-check, /plan-create, /harness-check
6. CI integration — workflow running all enforcement on every PR

---

Phase 1: Codebase Discovery

Before generating anything, build a thorough mental model. Every file you later create depends on this analysis being accurate.

Analyze these dimensions

1. Tech stack — Read package.json / Cargo.toml / go.mod / pyproject.toml. Identify language(s), framework, package manager, database, auth layer, API layer, hosting platform, test framework, CI/CD system.

2. Directory structure — Recursive listing (exclude node_modules, .git, dist, build, vendor). Map the module/domain decomposition pattern. Note src/ vs lib/ vs app/, monorepo vs single-package.

3. Domain boundaries — Identify feature modules, bounded contexts, or domain directories. Trace imports between them to map dependency directions. Identify shared/common code vs domain-specific code.

4. Existing documentation — Read CLAUDE.md, README.md, CONTRIBUTING.md, any existing docs/. Note what's documented, what's missing, what's stale.

5. Conventions — File naming patterns, export patterns, test file locations, logging patterns, error handling patterns, ID generation, data validation approach.

6. CI/CD — Check .github/workflows/, .gitlab-ci.yml, etc. Note existing lint/test/build steps.

Do NOT write files in this phase

Build the analysis internally. Summarize key findings to the user before proceeding — especially the domain boundaries and layer mapping, since these inform the architecture enforcement. Ask the user to confirm or correct before moving on.

---

Phase 2: Knowledge Base Scaffold

Create the docs/ directory. Read references/doc-templates.md for every template.

Directory structure

docs/
├── design-docs/
│   ├── index.md                # Catalogue with verification status
│   └── core-beliefs.md         # Golden principles (agent-first operating rules)
├── exec-plans/
│   ├── active/                 # Currently executing plans
│   ├── completed/              # Archived plans
│   └── tech-debt-tracker.md    # Known debt with severity and status
├── generated/                  # Auto-generated docs (DB schema, API specs)
├── product-specs/
│   └── index.md                # Catalogue of product specifications
├── references/                 # External reference material
├── enforcement/
│   └── index.md                # Catalogue of all enforcement rules
├── DESIGN.md                   # Design system and UI conventions
├── FRONTEND.md                 # Frontend architecture (only if applicable)
├── PLANS.md                    # How to create and manage execution plans
├── PRODUCT_SENSE.md            # Product context, user personas, business domain
├── QUALITY_SCORE.md            # Quality grades per domain and layer
├── RELIABILITY.md              # Reliability requirements, SLOs
└── SECURITY.md                 # Security model and requirements

Tailoring rules

• Only create FRONTEND.md if the project has a frontend
• Only create generated/db-schema.md if there's a database
• Populate core-beliefs.md with principles derived from the actual codebase patterns — not generic platitudes
• Populate QUALITY_SCORE.md with honest initial grades based on your analysis (test coverage, type safety gaps, documentation holes)
• Pre-fill tech-debt-tracker.md with obvious debt you spotted during analysis
• The generated/ directory is for docs that are or should be auto-generated from source — DB schema dumps, API spec extractions, dependency graphs

Core Beliefs

These are the golden principles that keep the codebase coherent for agents. Start with these universals, then add project-specific beliefs from your analysis:

1. Validate at boundaries — Parse and validate data at system edges. Trust types internally. Agents must not build logic on guessed data shapes.
2. Shared utilities over hand-rolled helpers — Centralize invariants. When the same pattern appears in 3+ places, extract it.
3. Repository is the source of truth — Design decisions, product context, architectural constraints: all versioned and in-repo. Slack threads and Google Docs are invisible to agents.
4. Progressive disclosure — Entry points are lean summaries pointing to details. No single file tries to contain everything.
5. Mechanical enforcement — If a rule matters, it's a linter or CI check, not a comment.

Add 3-5 project-specific beliefs derived from your codebase analysis (e.g., "all database access goes through the data layer", "no direct state mutation outside stores", "all API routes validate input with Zod schemas").

---

Phase 3: Architecture Documentation

Generate ARCHITECTURE.md from actual codebase analysis. Read references/architecture-guide.md for the layered architecture pattern in detail.

ARCHITECTURE.md sections

1. System overview — One paragraph: what the system does
2. High-level architecture — ASCII or mermaid diagram of major components
3. Domain map — Each domain/module with its single-sentence responsibility
4. Layer definitions — The layers this project uses (adapted from the reference model)
5. Dependency rules — Explicit allowed/forbidden edges between layers and domains
6. Cross-cutting concerns — How auth, logging, telemetry, feature flags are wired in
7. Key data flows — 2-3 critical user journeys traced through the layers

Adapting the layer model

The reference model is Types → Config → Data → Service → Runtime → UI. Map it to the actual codebase:

• Types/Schemas — Data shapes, validation schemas, type definitions
• Config — Configuration, constants, feature flags
• Data/Repository — Database access, external API clients, data fetching
• Service/Logic — Business logic, orchestration, domain rules
• Runtime — Server setup, middleware, routing, job runners
• UI/Presentation — Components, views, pages

Every existing directory gets mapped to a layer. Document deviations with rationale.

---

Phase 4: CLAUDE.md as Table of Contents

This is the critical file. Restructure or create CLAUDE.md as a lean ~100-line table of contents. The agent reads this first — it's the map, not the territory.

Structure

# [Project Name]

## Quick Start
[2-3 lines: install deps, run the project]

## Commands
[Essential commands only: dev, build, test, lint, harness:check]

## Architecture
→ See [ARCHITECTURE.md](./ARCHITECTURE.md)
[2-3 sentence summary]

## Knowledge Base
→ All documentation lives in [docs/](./docs/)

Key entry points:
- [Core Beliefs](./docs/design-docs/core-beliefs.md) — Engineering principles
- [Design Docs](./docs/design-docs/index.md) — Architectural decisions
- [Product Specs](./docs/product-specs/index.md) — Feature specifications
- [Active Plans](./docs/exec-plans/active/) — Current work
- [Quality Scores](./docs/QUALITY_SCORE.md) — Per-domain grades
- [Tech Debt](./docs/exec-plans/tech-debt-tracker.md) — Known debt
- [Enforcement Rules](./docs/enforcement/index.md) — All mechanical checks

## Conventions
[5-10 critical conventions. No more. Details live in docs/.]

## Enforcement
All rules are mechanically enforced via `[harness:check command]`.
→ See [docs/enforcement/](./docs/enforcement/) for rule details.

The litmus test

If CLAUDE.md exceeds ~120 lines, something belongs in docs/ instead. CLAUDE.md is a table of contents — when an agent needs to understand the system, it reads this file first and follows links to the depth it needs. That's progressive disclosure.

Preserve existing content

If there's already a CLAUDE.md, don't throw away useful content. Migrate detailed sections into the appropriate docs/ files, then replace them with pointers in the restructured CLAUDE.md.

---

Phase 5: Enforcement Tooling

Generate enforcement scripts tailored to the detected tech stack. Read references/enforcement-patterns.md for implementation patterns and code examples.

Script location and conventions

All enforcement scripts live in scripts/harness/. Every script:

• Exits 0 on pass, non-zero on fail
• Prints agent-friendly remediation instructions on failure — these messages become context when an agent hits a violation, so they must explain exactly what's wrong and how to fix it
• Is independently runnable
• Accepts a --fix flag where auto-remediation is possible

Required checks

1. Dependency direction (check-dependencies.{ts,py,sh}) Analyze imports to ensure they follow the declared layer ordering from ARCHITECTURE.md. Flag any import that crosses a forbidden boundary.

2. File size limits (check-file-sizes.sh) Flag source files exceeding a configurable threshold (default: 500 lines for source, 300 for tests). Large files are hard for agents to reason about — this keeps the codebase agent-legible.

3. Structured logging (check-logging.{ts,py,sh}) No raw console.log/print/fmt.Println in production code. Require the project's structured logger.

4. Doc freshness (check-doc-freshness.sh) Verify docs/ files have been modified within a configurable window. Validate all cross-links resolve. Check ARCHITECTURE.md references all current domains.

5. Naming conventions (check-naming.sh) Validate file names and export names match the project's conventions.

6. Architecture boundary tests Structural tests that run with the project's test framework. They import the module graph and assert no forbidden dependency edges exist.

Orchestrator

Create scripts/harness/check-all.sh that runs every check and reports a unified pass/fail. Add it as a package script:

{ "harness:check": "bash scripts/harness/check-all.sh" }

Or the equivalent for the project's build system.

CI integration

Generate a CI workflow (GitHub Actions / GitLab CI / whatever the project uses):

• Run harness:check on every PR
• Run doc freshness on a weekly schedule
• Post agent-friendly error summaries on failure (not just "check failed" — include which files violated which rules)

Configuration

Create .harness.json at the repo root for tunable thresholds:

{
  "fileSizeLimit": { "source": 500, "test": 300 },
  "docFreshnessWindowDays": 90,
  "layers": ["types", "config", "data", "service", "runtime", "ui"],
  "ignorePaths": ["scripts/", "generated/", "migrations/"]
}

---

Phase 6: Claude Code Configuration

Set up Claude Code-specific tooling for agent workflows. Read references/claude-commands.md for command templates.

Custom commands (.claude/commands/)

Create these commands that agents and humans can invoke:

Command	Purpose
doc-garden.md	Scan docs/ for stale, broken, or missing docs. Fix inline or flag gaps.
quality-check.md	Run quality scoring across all domains, update QUALITY_SCORE.md.
arch-check.md	Validate architectural boundaries, flag violations, suggest fixes.
plan-create.md	Create a new execution plan from a task description.
plan-complete.md	Mark an execution plan as completed and archive to completed/.
debt-log.md	Add an entry to the tech debt tracker.
harness-check.md	Run all enforcement checks and report results.

Sub-CLAUDE.md files

For codebases with distinct domains, create CLAUDE.md files in domain directories (20-30 lines each, domain-specific context only):

src/modules/auth/CLAUDE.md
src/modules/payments/CLAUDE.md

Only create these for domains that have enough specific context to warrant their own file.

Hooks

If appropriate for the project, configure Claude Code hooks:

• Post-file-edit: Run the relevant enforcement check on edited files
• Pre-commit: Run harness:check

---

Phase 7: Verification

After generating everything:

1. Run harness:check — Fix any violations. The current codebase state is the baseline; enforcement must pass from day one.
2. Validate docs/ structure — Every required file exists and has meaningful content (not just templates).
3. Validate cross-links — All markdown links in CLAUDE.md and docs/ resolve to real files.
4. Validate CLAUDE.md size — Under 120 lines.
5. Run architecture boundary tests — Must pass against current code.
6. Print summary — List every created file with its path.

Summary format

## Harness Engineering Initialized

### Knowledge Base
- docs/design-docs/          (N files)
- docs/exec-plans/           (N files)
- docs/product-specs/        (N files)
- docs/generated/            (N files)
- docs/enforcement/          (N files)
- ARCHITECTURE.md            ✓
- CLAUDE.md                  ✓ (N lines)

### Enforcement
- scripts/harness/           (N scripts)
- .harness.json              ✓
- CI workflow                ✓
- harness:check              ✓ (all passing)

### Claude Code
- .claude/commands/          (N commands)
- Sub-CLAUDE.md files        (N files)

### Next Steps
1. Review ARCHITECTURE.md — correct any mischaracterizations
2. Review core-beliefs.md — add project-specific principles
3. Review QUALITY_SCORE.md — adjust initial grades
4. Run /doc-garden to establish the baseline
5. Commit all generated files

---

Maintenance Guidance

After initialization, briefly explain to the user:

• Doc gardening — Run /doc-garden weekly to catch stale or broken docs
• Quality scores — Update after major changes via /quality-check
• Tech debt — Log immediately via /debt-log, pay down continuously
• Enforcement rules — Add new linters when new patterns emerge
• Core beliefs — Update when the team makes significant architectural decisions
• Exec plans — Use for any non-trivial multi-step work

The harness is a living system. Its value compounds as agents rely on it for context — entropy is the enemy, and mechanical enforcement is the antidote.