generating-codebase-harness

Generating a Codebase Harness

Overview

A harness is a folder of plain-language Markdown describing what an application does for its users, organized by end-to-end capability, for an AI help-center assistant to answer end-user questions. Build it natively: you read the code and write the docs yourself — you are the model in the pipeline.

Core principle: describe BEHAVIOR and OUTCOMES from the user's point of view; never how the system is built or secured.

Capture how the system behaves, not just what it offers. A support agent resolves a query ("why didn't my refund go through?") by understanding the system's decision logic — its conditions and branches, the states a thing moves through, the rules and limits a user runs into, and what the user sees when something fails. Record all of that, in plain language. This is a first-class goal, not an extra: an article that lists features but hides the conditions and failure modes is not diagnostic enough. Behavioral mechanics described in plain words are NOT technical or security detail — saying "a full refund is only available before the booking starts" reveals a product rule, not how anything is built. Read low and transparently about runtime behavior; stay silent about implementation.

(Canonical prompt wording this encodes lives in this repo's legacy/DESIGN.md Appendix A and legacy/harness_builder/prompts.py — see the write-up prompt's "CAPTURE CONDITIONAL BEHAVIOR" instruction and the conditions field in legacy/harness_builder/models.py.)

The hard rules (this is where attempts go wrong)

1. Never read secret-bearing files. Skip .env*, key/cert/credential files entirely — do not open them, do not echo any value.
2. Logic as a whole — no bifurcation. A capability spans the screen + server + background work. Merge those into ONE article. Never organize by frontend/backend, by service, or by folder.
3. No technical detail anywhere. No code identifiers, file names, framework/library/tech names (React, Rails, Postgres, …), infrastructure (hosts, IPs, ports, env var names), or data field names (user_id, total_cents, …). This does not prohibit describing behavior in plain words: conditions and branches ("if the booking hasn't started yet …"), the states a thing moves through, required inputs, and user-facing limits are all encouraged — they are what makes the harness diagnostic. Describe the rule, never the field or the code that enforces it.
4. Omit security mechanisms and secrets — but behavioral access help is allowed. You MAY write a behavioral article for user-facing access actions (signing in, signing out, resetting access) that covers only what the user does and sees. You must NOT describe or name how it is secured: no tokens/JWT/sessions, no "your session lasts N hours"/expiry mechanics, no credentials, no hashing/encryption, no permission rules — and never an article about the internal mechanism. Decision test: "How do I sign in? / I can't log in" → allowed, purely behavioral. "How is access enforced / how are sessions handled?" → omit entirely. Numbers: keep numbers that are product rules the user experiences while using a feature ("up to 5 photos", "refundable until the start time"); omit numbers that are security/expiry/rate-limit/infra mechanisms (session length, token/link expiry, lockout thresholds, retry/backoff internals).
5. Every file is navigable and rule-bound. index.md carries a global Rules / Prohibited section and a "Read this when" hint per entry; every article opens with a local Prohibited block.