agentleFS
Sign inStart free
felirangelpfelirangelp/harness-driven-dev/CLAUDE.md

harness-driven-dev

CLAUDE.md15 starsChanged 6 months agoMITView on GitHub

This is a demo Task Board (vanilla HTML/CSS/JS) used to demonstrate Harness-Driven Development: an approach where an AI agent enforces software best practices mechanically via scripts, hooks, and gates. The harness connects Linear (project management) with GitHub (code) through automated enforcement. The agent has 5 skills that connect with the harness: Note: DEMO-X is used as an example. Replace with your actual Linear team key prefix (e.g., HAR-5, EXP-1). The team key is set when you create your team in…

  • Reads credentials

The file

We split this CLAUDE.md into the rules it gives an agent

9 rules. About 0 are common, 3 are distinctive, and 6 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 6

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    No code without issue: Before touching code, run /start-issue.

    line 28
  2. Very specific:

    Refs, never Closes: Commit messages MUST contain Refs DEMO-XXX.

    line 29
  3. Very specific:

    NEVER use Closes, Fixes, or Resolves — they bypass harness gates.

    line 30
  4. Very specific:

    Mechanical Definition of Done: Use /close-issue to close issues.

    line 31
  5. Distinctive:

    NEVER close manually in Linear.

    line 32
  6. Distinctive:

    Evidence always: Every issue closure includes an audit trail comment in Linear.

    line 36
  7. Very specific:

    When gitleaks blocks a commit because a secret was hardcoded, run the /fix-secret skill.

    line 40
  8. Distinctive:

    Remove the secret from the code.

    line 43
  9. Very specific:

    Ensure .env.example documents the variable name (placeholder only).

    line 44

≈ “Common” is an estimate: at least 1 in 5 of the 26,980 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
CLAUDE.md

CLAUDE.md — Harness-Driven Development

Project

This is a demo Task Board (vanilla HTML/CSS/JS) used to demonstrate Harness-Driven Development: an approach where an AI agent enforces software best practices mechanically via scripts, hooks, and gates.

The harness connects Linear (project management) with GitHub (code) through automated enforcement.

Skills

The agent has 5 skills that connect with the harness:

SkillWhen to use
/create-issue <title>Create a new issue in Linear with acceptance criteria.
/start-issue DEMO-XALWAYS before writing code. Reads Linear issue, creates branch, moves to In Progress.
/close-issue DEMO-XALWAYS to finish work. Runs 3 gates (tests + CI + criteria), posts evidence, moves to Done.
/fix-secretWhen gitleaks blocks a commit. Moves the secret to env, asks the user to populate .env, WAITS for confirmation before retrying.
/statusCheck project dashboard: issues, branch, CI status.

Note: DEMO-X is used as an example. Replace with your actual Linear team key prefix (e.g., HAR-5, EXP-1). The team key is set when you create your team in Linear.

Harness Rules

  1. No code without issue: Before touching code, run /start-issue.
  2. Refs, never Closes: Commit messages MUST contain Refs DEMO-XXX. NEVER use Closes, Fixes, or Resolves — they bypass harness gates.
  3. Mechanical Definition of Done: Use /close-issue to close issues. NEVER close manually in Linear. The harness runs 3 gates first.
  4. No secrets in code: gitleaks blocks commits with secrets automatically. When it blocks, follow the Secret Blocked Flow below — never bypass it with --no-verify.
  5. Evidence always: Every issue closure includes an audit trail comment in Linear.

Secret Blocked Flow

When gitleaks blocks a commit because a secret was hardcoded, run the /fix-secret skill. This flow is mandatory and non-negotiable:

  1. Remove the secret from the code; read it from an environment variable.
  2. Ensure .env.example documents the variable name (placeholder only).
  3. Ask the user to put the real value in .env, then STOP.
  4. WAIT for the user's explicit confirmation that .env is ready. The agent MUST NOT retry the commit before this confirmation.
  5. Retry the commit (now clean) and continue (push → PR → /close-issue).

The agent NEVER reads, writes, or creates .env — the user owns secrets.

Commit Message Format

<type>: <short description>

<optional body>

Refs DEMO-XXX

Types: feat, fix, docs, test, chore, refactor

Scripts

ScriptPurpose
scripts/linear_client.pyGraphQL client for Linear API (get, move, comment, list)
scripts/close_issue.shGate script: tests + CI + acceptance criteria
scripts/check_issue_ref.shCommit-msg hook: enforces Refs DEMO-XXX
scripts/ci_failure_bridge.pyAuto-creates Linear bug when CI fails

Tech Stack

  • Frontend: HTML + CSS + vanilla JS (no frameworks)
  • Tests: Node.js + jsdom
  • Harness scripts: Python 3 (stdlib only) + Bash
  • CI: GitHub Actions
  • Project management: Linear

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free