Skip to content

AGENTS.md

Latest commit

 

History

History
68 lines (51 loc) · 3.7 KB

AGENTS.md

File metadata and controls

68 lines (51 loc) · 3.7 KB
Raw

AGENTS.md — For Agents Consuming This Kit

This repository is a distilled reference to Ryan Lopopolo's harness-engineering anthology. It is structured as a retrieval-optimized context bundle following the same principles it teaches.

What this repo is

A compact, opinionated guide to the 12 theses of harness engineering. Each thesis is a single markdown file under theses/ with:

  • A one-paragraph definition
  • The core argument
  • Key quotes and links to primary sources
  • An actionable checklist
  • A "how Zero applies this" section

What this repo is NOT

This is NOT a substitute for reading the original anthology at github.com/lopopolo/harness-engineering. This is a study guide and practical reference. When you need full depth, follow the source links in each thesis.

How to use this kit

From the CLI

npx @shift-zero/harness-kit          # List all 12 theses with summaries
npx @shift-zero/harness-kit scaffold # Generate AGENTS.md + ARCHITECTURE.md scaffolding for your repo
npx @shift-zero/harness-kit thesis 6 # Read thesis 6 in detail

As a reference bundle

When you encounter an unresolved decision while working on another repo:

  1. Identify which thesis addresses your gap (use the index below)
  2. Read that thesis from theses/
  3. Adapt the ideas to your target — don't copy file layouts or policies
  4. Let target-local truth govern the implementation

To improve an agent context directory

cd your-repo
npx @shift-zero/harness-kit scaffold --name my-project

This generates AGENTS.md and ARCHITECTURE.md templates following harness-engineering principles: just-in-time routing, clear ownership, and progressive disclosure.

Thesis index

# Thesis File Use when...
1 Hold the worker constant theses/01-fixed-worker.md Choosing or upgrading a model/agent, requalifying environment
2 Deploy into the private process-data iceberg theses/02-last-mile-deployment.md Deciding what context to put in a repo vs leave in live systems
3 Give one agent the whole job theses/03-whole-job.md Splitting work across agents; defining ownership boundaries
4 Route context just in time theses/04-just-in-time-context.md Designing AGENTS.md, runbooks, skills, progressive disclosure
5 Make capabilities legible and operable theses/05-tool-legibility.md Building tools, CLIs, MCP servers; designing tool output
6 Make the repository teach the agent theses/06-domain-modeling.md Structuring code; encoding nonfunctional requirements
7 Maximize autonomy inside explicit authority theses/07-authority.md Setting permissions, approval boundaries, recovery contracts
8 Prove the outcome in the real environment theses/08-proof.md Designing tests, CI, verification, and monitoring
9 Turn feedback into infrastructure theses/09-feedback.md Handling review comments, failures, MLD — making lessons durable
10 Preserve coherence and own lifetime risk theses/10-durable-systems.md Making long-term decisions, migrations, dependency ownership
11 Run known work as a continuous loop theses/11-continuous-maintenance.md Automating settled outcomes, gardening, scheduled refreshes
12 Optimize for measured effectiveness theses/12-effectiveness.md Deciding what to measure; evaluating harness investments