Harness Notes

Why initialization needs its own phase

Prepare the runway before asking the agent to fly.

Notes from Learn Harness Engineering · Lecture 06

preflight.console
1  Environment[✓] READY
2  Example test[✓] READY
3  Readiness doc[✓] READY
4  Task breakdown[✓] READY
5  Clean checkpoint[✓] READY
preflight> all_gates_ready ▋

Mixed session

Build while preparing. Pay later.

1
Start feature immediatelyVisible output wins attention.
2
Discover environment gapsMissing tools and configs interrupt work.
3
Accumulate unverified codeFeedback arrives after choices harden.
4
Rediscover next sessionUnknown conventions become rebuild cost.
vs.

Dedicated initialization

Prepare first. Ship faster.

1
Runnable environmentDependencies install and the app starts.
2
Example test passesThe verification system proves itself.
3
Readiness + task listThe repository explains how to proceed.
4
Clean checkpointImplementation begins from known-good state.

Multi-objective conflict

Features and infrastructure compete for attention.

Weak infrastructure

Tests and tools exist but are never fully verified.

Unverified accumulation

Code grows before feedback shapes the design.

Context waste

Every session spends budget recovering basics.

Assumption landmines

Unrecorded choices create contradictory tooling.

Core concepts

Initialization is a lifecycle phase with its own output, metrics, and acceptance criteria.

Initialization phase
A feature-free phase whose output is reliable infrastructure, not business code.
Startup readiness
The conditions that let a fresh session operate without verbal context.
Template vs. scratch
Templates encode proven structure; scratch work forces the agent to infer it.
Always ready to hand off
The repository alone explains state, operation, and next actions.
Time to first passing test
The key speed metric for initialization efficiency.
Subsequent-session success
The best quality measure: can later sessions execute without hidden knowledge?

The initialization contract

1

Runnable environment

  • Dependencies install
  • App starts cleanly
  • Commands documented
2

Verified test framework

  • Runner configured
  • Example test passes
  • Tests repeat locally
3

Readiness document

  • Start and test commands
  • Project structure
  • Current state
4

Ordered task breakdown

  • At least three tasks
  • Acceptance criteria
  • Sequence for success
5

Clean git checkpoint

  • Everything committed
  • Working tree clean
  • Known-good baseline

Four readiness conditions

CAN START

The environment runs without friction.

CAN TEST

At least one test passes locally.

CAN SEE PROGRESS

Tasks and criteria are visible.

CAN PICK UP NEXT STEPS

A fresh agent knows where to begin.

Template advantage

harness init <template> my-feature
  • Proven directory structure and tooling.
  • Fewer decisions and setup errors.
  • Project-specific work replaces repeated boilerplate.
  • Standard infrastructure becomes reusable knowledge.

Acceptance checklist

  1. make setup succeeds from scratch.01
  2. make test has one passing test.02
  3. A fresh session knows how to run and test.03
  4. Task breakdown contains at least three tasks.04
  5. All initialization work is committed.05

Evidence

31%
higher completion
dedicated phase
3–4
sessions
investment recovered
~60%
more rebuild time
mixed approach
<3 min
session 2 rebuild
dedicated approach
TAKEAWAY

Initialization produces reliability, not features.