AGENT SKILL

test-first-extract

Use when the user asks to EXTRACT or RELOCATE existing code into its own file, module, or component ("extract X", "split out Y", "pull Z into its own file", "decompose god-file"). NOT for net-new features (use tdd-feature-build) or behavior changes (use fix-bug). Enforces the 9-step extraction with isolated unit tests + integration regression tests as a two-tier safety net.

License 许可
Apache-2.0
最近更新
2026-11-09
Stars
★ 0
Forks
0

01 前言 Front Matter

name
test-first-extract
description
Use when the user asks to EXTRACT or RELOCATE existing code into its own file, module, or component ("extract X", "split out Y", "pull Z into its own file", "decompose god-file"). NOT for net-new features (use tdd-feature-build) or behavior changes (use fix-bug). Enforces the 9-step extraction with isolated unit tests + integration regression tests as a two-tier safety net.

03 SKILL.md 正文

Test-First Extraction

You are extracting code from one location into a new, focused file. The risk is silent regression — props dropped, callbacks rewired wrong, state coupling broken. The discipline below makes that risk catchable.

Pre-flight

  1. Read QUALITY-BAR.md for the strictness rules and refactor discipline.
  2. Identify the parent file the code is being extracted FROM and the target path it's being extracted TO.
  3. Detect / create the test infrastructure at the target path's sibling (Foo.jsx ↔ Foo.test.jsx). If the project uses a different convention (e.g. __tests__/ mirror), match it.
  4. Read the integration regression test file at the parent's level (or create one if absent). This is where you'll add the cross-cutting tests that catch wiring breaks.

The 9-step extraction

Step 1: Survey the target

Read the inline code being extracted. Build a complete inventory:

  • Props the new component will receive (with types if known).
  • State owned by the new component vs. owned by the parent.
  • Callbacks the new component will fire upward.
  • Module-level dependencies (constants, utility functions, other components, context). Will the new file import these, or will the parent pass them as props?
  • Side effects (effects, refs, API calls). Where do they belong after extraction?

If anything in the inventory is itself inline in the parent (e.g., a 1,600-line component the wrapper depends on) — STOP. Either extract that dependency first, or pivot to a different extraction. Never use render-props or import-circularity hacks to work around blocking inline dependencies.

Step 2: Write strict isolated unit tests FIRST

Create <Target>.test.{jsx,ts,py} at the target path's sibling. Import from the target file path (which doesn't exist yet — that's intentional).

Cover EVERY meaningful prop / arg / branch / edge case from your survey:

  • Default props → renders correctly?
  • Each prop variation → behaves correctly?
  • Each callback → fires with the right args?
  • Each conditional branch → both sides covered?
  • Edge cases: empty arrays, null/undefined, large inputs?

Apply the strictness rules from QUALITY-BAR.md:

  • getByRole over queryAllByText.
  • Exact counts where uniqueness is expected.
  • jest-dom matchers (toBeInTheDocument, toBeDisabled, toHaveAttribute).
  • userEvent over fireEvent for interactions.

Step 3: Confirm tests fail with file-not-found

Run just the new test file. They MUST fail with file-not-found (or import error). That's the correct "red" state.

If they pass somehow → you imported from the wrong path; fix. If they fail for any other reason → fix the test, don't proceed.

Step 4: Add 1–3 integration regression tests in the parent's test file

Open the parent's integration test file (e.g., ScriptureEngineV2.regression.test.jsx). Add tests that exercise the about-to-be-extracted UI/behavior THROUGH the live parent.

These tests:

  • Render the parent with the harness mocks.
  • Assert observable behavior (text on screen, fetch URL fired, click → callback) — NOT implementation details.
  • Will survive the move from inline JSX → child component without modification.

Step 5: Confirm regression tests pass against current code

Run the integration tests. They MUST pass against the current (still- inline) code. This establishes the baseline.

If they fail → your test is wrong; fix until green. The baseline must be solid before you touch the code.

Step 6: Create the target file with the extracted code

Now (and only now) create <Target>.{jsx,ts,py} and copy the inline code into it, transformed into a function/class accepting the props you defined in step 1.

Keep behavior IDENTICAL. This is a relocation, not an improvement opportunity. Resist the urge to "clean up while you're here" — that expands scope and undermines the test net.

Step 7: Run isolated tests — confirm pass

Run just the new test file. All tests should pass. If any fail, the extraction has a real bug — fix the implementation (not the test).

Step 8: Remove inline copy from parent + add import

Open the parent. Remove the inline code. Add:

import { Target } from './path/to/Target.jsx';

Replace the inline JSX with <Target {...props} />.

For React: pass props the parent owns; wire callbacks to parent's state setters.

Step 9: Run the FULL suite — confirm green; commit

Run every test in the project — unit + integration + regression. All must pass.

If anything is red → revert the parent edit (step 8), debug, retry.

If green → commit using QUALITY-BAR.md commit format:

refactor(scope): extract <Target> from <Parent>

Process: tests-first (10 strict unit tests for the target + 2
regression tests in the parent suite); confirmed file-not-found
failure; created target; verified isolated 10/10; replaced inline
~N lines with <Target …>; full suite NN/NN green.

Behavior: no behavior change — pure relocation.

Numbers: parent file XXX → YYY lines (-N). Tests: AA → BB (+N).

Assisted-by: Claude (claude-tdd-pro 0.3.0)

Common pitfalls

  • Skipping step 3 (confirm red): if you don't confirm the new tests fail with file-not-found, you might write tests that accidentally pass against some other code path. The red is the proof you're testing the right thing.
  • Skipping step 5 (confirm regression baseline): if you don't run the regression tests against the CURRENT code first, you don't know whether the test itself works. After extraction it could pass for the wrong reason.
  • Cleaning up during the move: combine extraction with refactoring → you can't tell which change broke things if the suite goes red. Pure relocation first, refactor in a follow-up commit.
  • Render-prop / import-circularity hacks: if the target depends on something also inline in the parent, extracting the wrapper is just papering over the problem. Extract the dependency first.

Sub-extraction strategy for huge targets

If the "target" is a 1,000+ line block:

  1. Identify SUB-boundaries within it (the next-smaller cohesive units).
  2. Extract the smallest, most-self-contained sub-piece first.
  3. Repeat until the parent block has shrunk to something reasonable.
  4. Then extract the now-smaller block as a coherent component.

This is the "wave" pattern — each wave is its own commit, each commit runs through the full 9 steps.

04 同仓库更多 Skills

drumfiend21
drumfiend21/claude-tdd-pro

tdd-feature-build

Use when the user describes a NEW feature to add ("add X to Y", "implement Z", "build a feature that…", "make it possible to…"). Enforces TDD — failing test first, minimum code to pass, refactor. Refuses to ship code without a test that demonstrably catches its absence. Does NOT trigger on bug fixes (use bug-fix-discipline) or refactors (use test-first-extract). Will ask 1-3 clarifying questions before writing any code; safe to delegate from /feature command.

★ 0
drumfiend21
drumfiend21/claude-tdd-pro

sync

Multi-machine git-backed sync of local TDD Pro state via the `tdd-pro-sync` branch. Use when operators run claude-tdd-pro on more than one machine and want their FAILURE-LOG, decisions, audit checkpoints, workflow state, operator-curated URL registries, operator/community trees, and paywalled attestations to follow them between hosts.

★ 0
drumfiend21
drumfiend21/claude-tdd-pro

strict-component-tests

Use when writing or reviewing test files. Enforces strict assertions that actually catch regressions (getByRole, exact counts, jest-dom matchers) in contrast to permissive tests (queryAllByText length > 0) that pass against broken UIs. References QUALITY-BAR.md for the canonical strictness rules.

★ 0
drumfiend21
drumfiend21/claude-tdd-pro

spec

暂无简介

★ 0
drumfiend21
drumfiend21/claude-tdd-pro

spec-first

Use when the user describes a non-trivial feature or system that should be specified in writing before any code is written. Pattern from Geoffrey Huntley's "Ralph" loop, OpenSpec, intent-driven.dev, and Kent Beck's "augmented coding" framing — specs+tests are the durable artifact, code is the disposable one. Produces a Markdown spec document that the user reviews; only after approval does any code get written (typically via tdd-feature-build or /feature).

★ 0
drumfiend21
drumfiend21/claude-tdd-pro

reject-bad-tooling

Use whenever the conversation involves dependency suggestions, CI/CD design, "automated code improvement," lint/security fixes, or "tools to make my code better." Refuses specific anti-patterns from a prior session that produced more harm than help — and explains why, with the better alternative. Triggers on suggestions of force-fix flags, auto-commit CI workflows, jscodeshift codemods on untested code, fake package names, and similar.

★ 0