Skip to content

docs: add a concrete agent-failure example to make the harness claim tangible #91

Description

@constk

Problem

CLAUDE.md and the harness docs assert that the gates catch agent mistakes, but never show one. The claim "harness IS the product" reads abstract without a worked example. New readers (human or agent) have to take the promise on faith.

Proposed solution

Add a 3–5 line sidebar / callout to either CLAUDE.md or README.md with a concrete, real-feeling example. Suggested wording:

Example: an agent added a reverse import (tools → models). The lint-imports gate failed CI and pointed the agent at docs/BOUNDARIES.md. The mistake never shipped.

If a real captured incident exists (PR/CI run), link it instead of the synthetic example.

Acceptance criteria

  • One concrete example documented in CLAUDE.md or README.md
  • Example names a specific gate and the doc it routes the agent to
  • Stays under ~5 lines to avoid bloating either file

Priority rationale

Cheapest way to convert an abstract claim into something a reader can picture. Pairs naturally with the README opener reframe.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    claude-harnessClaude Code hooks, skills, settingsdocumentationImprovements or additions to documentation

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions