spec-kit-specify（规格套件指定）

Spec Kit Specify

Create or refresh the feature specification for the active Spec Kit feature.

Invocation Notice

• Inform the user when this skill is being invoked by name: spec-kit-specify.

When to Use

• Start a new feature and create the first spec.md.
• Convert free-form requirements into a structured, testable, implementation-agnostic specification.
• Rework an existing spec draft so it is ready for spec-kit-clarify or spec-kit-plan.

When Not to Use

• Clarify ambiguity in an already-written spec without redrafting it (spec-kit-clarify).
• Generate design artifacts or tasks from an approved spec (spec-kit-plan, spec-kit-tasks).
• Reconcile cross-artifact drift in an existing feature (spec-kit-reconcile).

Router Fit

• Primary route from spec-kit when spec.md does not exist yet.
• Downstream: hand off to spec-kit-clarify (if high-impact ambiguity remains) or spec-kit-plan (if spec is ready).

Preconditions

• User provided a non-empty feature description.
• Run from repository root (or a subdirectory inside the repository).

Workflow

1. Normalize input:

- Treat the full user request as the feature description. - If empty, stop: ERROR: No feature description provided.

1. Generate a short branch suffix (2-4 words, kebab-case):

- Preserve meaningful technical terms/acronyms. - Prefer action-noun phrasing (for example user-auth, bulk-export-audit-log).

1. Bootstrap feature branch and spec exactly once:

- Run scripts/create-new-feature.sh --json --short-name "<short-name>" "<feature description>". - Do not manually pre-compute branch numbers; let the script assign the next number. - Parse JSON output and capture: - BRANCH_NAME - SPEC_FILE - FEATURE_NUM - Derive FEATURE_DIR as dirname(SPEC_FILE).

1. Load template context:

- Preferred template: {REPO_ROOT}/templates/spec-template.md. - Fallback template: assets/spec-template.md. - Preserve heading order from the selected template.

1. Draft spec.md content (focus on WHAT/WHY, not HOW):

- Fill prioritized user stories with independent tests and acceptance scenarios. - Write testable functional requirements. - Add edge cases and scope boundaries. - Add measurable, technology-agnostic success criteria. - Include key entities when data is central. - Use reasonable defaults and document assumptions when needed.

1. Clarification policy while drafting:

- First, make informed defaults using domain norms. - Add [NEEDS CLARIFICATION:...] only for high-impact uncertainty. - Hard limit: at most 3 clarification markers. - Prioritize by impact: scope > security/privacy > UX > technical detail.

1. Write the spec to SPEC_FILE.
2. Create and run requirements quality validation:

- Create FEATURE_DIR/checklists/requirements.md. - Validate spec against this checklist: - No implementation details (frameworks, languages, APIs, internal architecture). - Mandatory sections are complete. - Requirements are unambiguous and testable. - Success criteria are measurable and technology-agnostic. - User scenarios and edge cases are covered. - Scope boundaries, dependencies, and assumptions are explicit. - No unresolved [NEEDS CLARIFICATION] markers for plan-ready specs. - If non-clarification issues fail, revise spec and re-validate (max 3 passes).

1. If clarification markers remain after validation:

- Ask up to 3 numbered clarification questions total. - For each question, present 2-3 concrete options plus a short custom answer path. - Wait for user responses, update spec.md, then re-run validation.

1. Report completion:

• Branch name.
• spec.md path.
• requirements.md path and pass/fail summary.
• Recommended next step:

- spec-kit-clarify if high-impact ambiguity remains. - spec-kit-plan if ready.

Output

• Active feature branch from scripts/create-new-feature.sh
• specs/<feature>/spec.md
• specs/<feature>/checklists/requirements.md
• readiness handoff for spec-kit-clarify or spec-kit-plan

Common Mistakes

• Writing implementation design into the spec instead of user-visible behavior and outcomes.
• Leaving vague requirements that cannot be acceptance-tested.
• Asking too many clarification questions instead of making reasonable defaults.
• Running feature bootstrap script multiple times for one request.

References

• references/spec-kit-workflow.dot
• scripts/create-new-feature.sh
• assets/spec-template.md
• https://github.com/github/spec-kit/blob/9111699cd27879e3e6301651a03e502ecb6dd65d/templates/commands/specify.md