agentleFS
Sign inStart free
atgreenatgreen/hackinator/skills/test-first/SKILL.md

test-first

Skill1 starsChanged 3 months agoMITView on GitHub

Use when implementing keeper code — any behavior meant to last, and especially when fixing a bug. Triggers on writing a function/feature you intend to keep, "add a test", "TDD", or the urge to write the code first and test it "after". Not for verifying a finished change before claiming it works — that's evidence-before-claims

24 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use security-sweep, refactor and 3 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • n24q02mSkill

    security-sweep

    Graph-driven security sweep -- scan for dangerous sinks, then rank each finding by whether an entry point can actually reach it, and triage the rest into suppressions.

    Also in 3 projects that use this

  • GitHubSkill

    refactor

    Surgical code refactoring to improve maintainability without changing behavior. Covers extracting functions, renaming variables, breaking down god functions, improving type safety, eliminating code smells, and applying design patterns. Less drastic than repo-rebuilder; use for gradual improvements.

    Also in 4 projects that use this

  • MicrosoftSkill

    api-design

    Guide for designing and documenting RESTful APIs. Use when asked to design an API, create endpoints, or document an API.

    Also in 3 projects that use this

  • GoogleSkill

    code-review

    Adversarial systems, concurrency, memory-model, and architecture code review protocol. Use this skill whenever asked to review code, PRs, diffs, or branches in Filament.

    Also in 4 projects that use this

  • SentrySkill

    skill-creator

    Create new agent skills following the Agent Skills specification. Use when asked to "create a skill", "add a new skill", "write a skill", "make a skill", "build a skill", or scaffold a new skill with SKILL.md. Guides through requirements, writing, registration, and verification.

    Also in 3 projects that use this

The file

We split this skill into the rules it gives an agent

5 rules. 0 are common, 5 are distinctive, and 0 are very specific to this project.

  • 0

    Common

    Most of the 20 edited versions we read keep these.

  • 5

    Distinctive

    This author's own choices. Worth a look.

  • 0

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    If you didn't watch the test fail, you don't know it tests the right thing.

    line 14
  2. Distinctive:

    When in doubt about whether something is a keeper, it's a keeper.

    line 36
  3. Distinctive:

    Watch it fail (mandatory): Run it. Confirm it fails *for the right reason* — the behavior is missing, not the test is misspelled.

    line 41
  4. Distinctive:

    Over-building in GREEN: Write only what the test demands.

    line 69
  5. Distinctive:

    Testing the mock instead of the behavior: If the test would pass with the real logic deleted, it's testing nothing.

    line 71

“Common” is measured: kept by at least 6 in 10 of the 20 edited versions of this file we could read. “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
SKILL.md

Test-First

Overview

Core principle: For code you intend to keep, write the test before the code, and watch it fail before you make it pass. A test written after the code asks "what does this do?"; a test written first asks "what should this do?" — and only the second one can catch the code being wrong.

If you didn't watch the test fail, you don't know it tests the right thing. It might pass because of a typo, a stubbed return, or nothing at all.

The Iron Law

NO KEEPER CODE WITHOUT A FAILING TEST FIRST

Wrote the code before the test? Delete it and start over. Not "keep it as reference," not "adapt it while I write the test" — delete. The value was the watched failure, and you can't get it back by testing code that already works.

Scope: What Counts as "Keeper"

This law governs code meant to last. It does not govern:

  • Spikes and throwaway probes — exploration is exempt by design. That's the whole point of spike-and-stabilize: learn in the ugly spike, then rebuild the answer test-first in the stabilize phase. The spike is where you're allowed to skip tests; the keeper version is not.
  • Generated code, config, and trivial declarations with no behavior to test.

When in doubt about whether something is a keeper, it's a keeper.

RED → GREEN → REFACTOR

  1. RED — write one small test for one real behavior. Real behavior, not a mock of it.
  2. Watch it fail (mandatory). Run it. Confirm it fails for the right reason — the behavior is missing, not the test is misspelled. A test that fails because of a typo has told you nothing.
  3. GREEN — write the simplest code that passes. No extra generality, no features the test didn't ask for. Then run it: this test passes, and the tests around what you just touched still pass (evidence-before-claims scopes how far "around" reaches — usually this module and its callers, not the whole suite on every cycle).
  4. REFACTOR — clean it up while staying green. No new behavior in this step (that needs its own RED). This is also where whittler naturally takes over for the craft pass.

Bugs Get a Failing Test First

A bug fix starts with a test that reproduces the bug — and fails. Watch it fail (red), fix it (green). That failing-then-passing test is your proof the bug is real and your guard against its return. A "fix" with no reproducing test is a guess.

Rationalizations — All Mean "Start Over"

ExcuseReality
"I'll write tests after"Tests-after pass immediately and prove nothing. You skipped the watched failure.
"It's too simple to test"Simple code breaks too, and a simple test costs seconds.
"I already tested it by hand"Manual checks aren't repeatable and don't guard against regressions.
"I'll lose the code I wrote"You keep the understanding, which is the part that mattered. Rebuild it green.
"This is basically a spike"Then say so and treat it as one — throwaway. If you're keeping it, it's keeper code.

Common Mistakes

  • Skipping the watched failure. GREEN that was never RED is a test you can't trust.
  • Over-building in GREEN. Write only what the test demands; save generality for a test that needs it.
  • Adding behavior in REFACTOR. New behavior needs a new failing test first.
  • Testing the mock instead of the behavior. If the test would pass with the real logic deleted, it's testing nothing.

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.

Reviews can't be read right now.

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