Skip to content

Instantly share code, notes, and snippets.

@aleksejkozin

aleksejkozin/feature.md

Created February 14, 2026 20:48
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save aleksejkozin/503ac7ded8c3941565036b383cbc09b3 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save aleksejkozin/503ac7ded8c3941565036b383cbc09b3 to your computer and use it in GitHub Desktop.
Download ZIP
Raw
feature.md
name description argument-hint user-invocable
feature
Use when the user asks to add, change, or refactor functionality. Research-driven TDD with refactoring and deduplication.
<feature description>
true

Feature: $ARGUMENTS

You are implementing a feature using a rigorous sequence of Research → Development → Refactor → Deduplication. You MUST complete every phase. Announce each phase transition explicitly (e.g. "Phase 3: Refactor").

Follow all project rules in CLAUDE.md.

Phase 1: Research

Goal: deeply understand the problem before writing any code.

  1. Read the feature description carefully. Restate it in your own words.
  2. Explore the codebase — find all relevant files, models, handlers, tests.
  3. Think about how to implement it. Consider edge cases, race conditions, security, existing patterns.
  4. Ask the user questions about anything unclear or ambiguous. It is GOOD to ask questions. Do not guess.
  5. Repeat steps 2-4 until you have a clear mental model of the change.

Output: a short summary of your plan (which files change, what the test will assert). Store the summary in an md file, update it if needed, the summary should be easily found by a fresh AI agent

Phase 2: Development (TDD)

Goal: implement the feature test-first in small increments.

Loop:

  1. Write a test (or expand an existing test) that describes the next piece of behavior.
  2. Run the test. Confirm it is RED. If it is green, your test is not testing anything new — fix it.
  3. Write the minimum production code to make the test GREEN.
  4. Re-read the code you just wrote. If you see duplication, refactor it out before moving on.
  5. Run lint and the full test suite.
  6. If anything broke, fix it before continuing.
  7. If you hit something unexpected or hard, switch back to Phase 1 — research, think, ask questions. Document findings in a markdown file under .claude/reviews/ so future Claude instances can find them.
  8. Go to step 1 for the next piece of behavior.

Keep cycles small. One behavior per cycle.

Phase 3: Refactor

Goal: improve the solution now that it works.

  1. Run the full test suite one more time. All green.
  2. Re-read all the code you wrote (and changed). Do a self-review:
    • Is this a good solution? Any pain points, bugs, race conditions, security vulnerabilities?
    • Is is a robust solution? Will it break easily under some future mutations? Is it brittle to mutations?
    • Is there duplicated logic? Can anything be simplified?
    • Are the tests testing behavior (not implementation)? Will they survive a refactor?
    • Are there too many tests? Merge tests that cover the same behavior from different angles. One test per distinct behavior, not per code path. Prefer adding assertions to an existing test over creating a new test that repeats the same setup.
  3. Step back and look at the overall architecture your change touches. Could it be simplified? Fewer moving parts is always better.
  4. Write a short code review as .claude/reviews/<feature-name>.md. Include:
    • What was implemented
    • Key decisions and trade-offs
    • Known limitations or future work
  5. Now refactor. You are allowed to do big refactors if the new approach is better. Don't be afraid to restructure — but keep all existing features working.
    • If refactoring touches other systems, that's fine — as long as tests stay green.
    • If tests need to change, be careful: ask yourself "am I fixing the test because I introduced a bug, or because the behavior genuinely changed?" Never hide a bug behind a test fix.
  6. If the refactor is significant, go back to Phase 1 to gather more context, then through Phase 2 to verify with tests.
  7. Run the full suite again after refactoring.

If there are known limitations, then work on them. Basically recursively call this skill on known limitations

Phase 4: Deduplication Sweep

Search the codebase for repeated logic where extraction would be significant and beneficial. For each one, treat it as a new feature and run this entire skill recursively. Repeat until no more worthy duplication remains (max 3 iterations).

When extracting, if every caller passes the same value for a parameter, it's not a parameter — it's an implementation detail. Bake it into the function.

When to Stop

Stop when ALL of these are true:

  • The feature works as described
  • All tests pass (including pre-existing ones)
  • Lint and build pass
  • You have reviewed your own code and are satisfied
  • The review file exists in .claude/reviews/
  • There is nothing stupid or silly in the code
  • Phase 4 sweep found no patterns worth extracting (or they have been extracted)

Report what you implemented, what tests you wrote, and any decisions you made.

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