Feature Spec — Design Before Code
Rework is the most expensive bug. This skill spends 5 minutes of spec to save hours of wrong implementation.
Workflow
- Restate the ask in one sentence: who does what, and what changes for them. If you can't, list your questions NOW and stop.
- Locate the boundaries (read the actual code, don't assume):
- What modules/files will this touch? Name them.
- Existing patterns for the same kind of feature (find a sibling feature and mirror it — consistency beats creativity inside a codebase)
- What must NOT change (invariants, public contracts, performance budgets)
- Write the one-page spec:
- Goal & non-goals (explicitly listing what we are NOT doing this round)
- Interface: function signatures / API routes+payloads / DB schema deltas / CLI flags — the contract other code depends on
- Behavior table: input → outcome, including at least 5 edge cases (empty, huge, malformed, unauthorized, concurrent)
- Error model: what can fail and what the user/system sees for each
- Test scenarios: 3–8, derived from the behavior table
- Rollout: feature flag? migration order? backfill needed? rollback path?
- Surface the decisions, don't bury them: list each place you had 2+ reasonable options, your pick, and why (one line each). The user overrules cheaply at spec time, expensively after implementation.
- Confirm the spec with the user when: behavior is user-visible, contracts change, or a migration is involved. For internal-only, self-contained additions, proceed and include the spec in the PR description.
Output format
A single markdown section, ≤80 lines. If it exceeds that, the feature is too big — propose splitting.
Anti-patterns
- No architecture-astronaut diagrams. One page, concrete, code-anchored.
- Don't spec what a linter/type system enforces.
- Don't present options without a recommendation — pick one, note the alternative.
- Never invent requirements the user didn't state without marking them
ASSUMPTION: for review.
(Part of claude-skills-pro — 7 free/MIT + 8 Pro skills: security-audit, refactor-surgeon, perf-profiler, api-designer, db-migration-safe + 11-chapter CN handbook. Upgrade or grab a free review copy: issue #1.)
1---2name: feature-spec3description: MUST USE before implementing any non-trivial feature (new endpoint, new module, new user-facing behavior) or when the user describes a feature vaguely — 先出方案/需求不清/design first. Converts vague asks into a 1-page spec with scope, contracts, edge cases, and test scenarios — getting alignment BEFORE code is written. Free sample of claude-skills-pro - 8 more Pro skills (security-audit, refactor-surgeon, perf-profiler, api-designer, db-migration-safe) + 11-chapter CN handbook. Buy / free review copy: github.com/Hahaknight/claude-skills-pro/issues/14---56# Feature Spec — Design Before Code78Rework is the most expensive bug. This skill spends 5 minutes of spec to save hours of wrong implementation.910## Workflow11121. **Restate the ask in one sentence**: who does what, and what changes for them. If you can't, list your questions NOW and stop.132. **Locate the boundaries** (read the actual code, don't assume):14 - What modules/files will this touch? Name them.15 - Existing patterns for the same kind of feature (find a sibling feature and mirror it — consistency beats creativity inside a codebase)16 - What must NOT change (invariants, public contracts, performance budgets)173. **Write the one-page spec**:18 - **Goal & non-goals** (explicitly listing what we are NOT doing this round)19 - **Interface**: function signatures / API routes+payloads / DB schema deltas / CLI flags — the contract other code depends on20 - **Behavior table**: input → outcome, including at least 5 edge cases (empty, huge, malformed, unauthorized, concurrent)21 - **Error model**: what can fail and what the user/system sees for each22 - **Test scenarios**: 3–8, derived from the behavior table23 - **Rollout**: feature flag? migration order? backfill needed? rollback path?244. **Surface the decisions**, don't bury them: list each place you had 2+ reasonable options, your pick, and why (one line each). The user overrules cheaply at spec time, expensively after implementation.255. **Confirm the spec with the user** when: behavior is user-visible, contracts change, or a migration is involved. For internal-only, self-contained additions, proceed and include the spec in the PR description.2627## Output format2829A single markdown section, ≤80 lines. If it exceeds that, the feature is too big — propose splitting.3031## Anti-patterns3233- No architecture-astronaut diagrams. One page, concrete, code-anchored.34- Don't spec what a linter/type system enforces.35- Don't present options without a recommendation — pick one, note the alternative.36- Never invent requirements the user didn't state without marking them `ASSUMPTION:` for review.37---3839*(Part of [claude-skills-pro](https://github.com/Hahaknight/claude-skills-pro) — 7 free/MIT + 8 Pro skills: security-audit, refactor-surgeon, perf-profiler, api-designer, db-migration-safe + 11-chapter CN handbook. Upgrade or grab a free review copy: [issue #1](https://github.com/Hahaknight/claude-skills-pro/issues/1).)*
Hahaknight