A lightweight spec kit for Claude Code that sharpens your specifications through structured interviews.
Turn a user story, ticket, or feature idea into a specification that Claude Code can implement correctly on the first pass.
You run /interview feature-name, paste your business requirements, and Claude fills in the technical gaps — codebase patterns, prohibitions, decision trees, edge cases — through a structured interview using multiple-choice questions grounded in your actual code. The output is a single markdown spec. You review it, then a fresh Claude Code session implements it cleanly.
/plugin marketplace add rasmusHochreuter/TheInterviewer # add the registry
/plugin install interview@interview-marketplace # install the plugin
/interview Add a new feature that allows the users to change password
The spec is a one-shot planning artifact, not a living document. Once the feature is implemented, you don't update the spec and re-run implementation. Bugs and enhancements are handled the normal way — you just tell Claude what to fix. The spec captured your intent, Claude internalized it, and then it got out of the way.
Other spec tools (spec-kit, Pimzino, adrianpuiu) pioneered spec-driven development for AI agents. TheInterviewer borrows ideas from all of them (see Acknowledgments), but takes a different approach based on the methodology from Focus on "Don'ts" to Build Systems That Know When to Say No:
- Don'ts over docs. Existing tools focus on what to build. TheInterviewer adds a dedicated phase for what to never do — prohibitions, decision trees for ambiguous cases, and escalation boundaries. Every don't gets a matching negative test.
- The spec stays out of the code. No
// REQ-001, no// See spec section 4.2, no traceability IDs. The implementing session internalizes the spec and writes code as if a developer simply knew the domain. - Codebase-grounded questions. Phase 0 silently reads your project, so every question references your actual patterns — "I see three error handling approaches in your codebase, which fits here?" instead of "How should errors be handled?"
- Zero setup. If your project doesn't have an
AGENTS.mdorCLAUDE.md, TheInterviewer creates one on first run with conventions discovered from your codebase. It supports both the vendor-agnosticAGENTS.mdstandard and Claude-specificCLAUDE.md, including projects that useAGENTS.mdas the primary file withCLAUDE.mdas a thin shell. Every future interview keeps your conventions up to date.
Claude reads your code first, then asks questions grounded in what it found. Instead of open-ended questions like "How should errors be handled?", it presents options derived from your actual codebase:
"I see three error handling patterns in your codebase. Most request handlers return a result object, a few throw exceptions caught by middleware, and one module uses inline checks.
For this feature:
A) Result object — consistent with most of your code, caller gets structured errors
B) Throw exception — simpler, middleware handles it uniformly
C) Inline checks — if the rules are tightly coupled to business logic
D) Something else
I'd recommend option A since 80% of your codebase follows that pattern."
Recognition beats recall. Picking from informed options is faster, more accurate, and surfaces approaches you might not have considered.
| # | Phase | What Happens |
|---|---|---|
| 0 | Codebase Recon | Claude silently reads your architecture, DI, error handling, test patterns. Detects AGENTS.md / CLAUDE.md — creates a conventions file if missing, or appends conventions if lacking |
| 1 | Questions | Presents findings, asks about reference implementation and scope |
| 2 | Requirements | Guided choices about entry points, data, integrations |
| 3 | Don'ts | Presents inferred constraints for confirmation, probes for prohibitions |
| 4 | Decisions | Drafts a decision tree, you correct it |
| 5 | Relationships | Domain rules, tier differences, temporal constraints |
| 6 | Guardrails | Failure modes, retry strategies, observability |
| 7 | Acceptance Criteria | Drafts test criteria, you validate with checkmarks |
| 8 | Self-Audit + Scorecard | Verifies consistency, scores spec on 4 axes (Completeness, Clarity, Constraints, Specificity), displays results |
Output: .claude/specs/<feature-name>.md
Add the marketplace and install the plugin:
/plugin marketplace add rasmusHochreuter/TheInterviewer
/plugin install interview@interview-marketplaceOr browse interactively — run /plugin, go to the Discover tab, and select interview.
# From the repo root
mkdir -p .claude/skills/interview/examples
cp skill/SKILL.md .claude/skills/interview/
cp skill/examples/order-cancellation-spec.md .claude/skills/interview/examples/Commit the skills with your repo so the whole team has them.
/interview users need to reset their password via email
Paste your user story, ticket description, or just describe the feature. Claude reads your codebase, walks you through the 8-phase interview to fill in the technical details, and saves the spec to .claude/specs/password-reset.md.
Open a fresh Claude Code session and tell it:
Implement the feature spec at
.claude/specs/password-reset.md
A fresh session gives Claude the full context window for coding. The spec contains everything it needs — reference implementation, prohibitions, decision tree, acceptance criteria — so Claude implements the feature following your established patterns without you repeating anything.
TheInterviewer works with any language and framework — Phase 0 reconnaissance adapts to whatever codebase it finds. These customization options let you fine-tune the experience:
Your conventions file (AGENTS.md or CLAUDE.md) captures project conventions that ground every interview. TheInterviewer detects whichever your project uses — including the common pattern where AGENTS.md holds the actual conventions and CLAUDE.md is a thin shell pointing to it. If neither exists, it creates one on first run and updates it after each interview with new conventions discovered during the process. You can edit it anytime to:
- Ground questions in your tools — if your conventions file says "Use: NSubstitute", Claude won't offer Moq as an option
- Pre-populate don'ts — "Don't use: AutoMapper" becomes a pre-checked constraint in Phase 2
- Set naming conventions — so the spec's file list and entity names match your patterns
- Flag deprecated patterns — so Claude never suggests the old
OrderServiceclass
These conventions pre-populate constraints in Phase 2, so you confirm them instead of re-stating them for every feature.
Two .NET convention templates are available in templates/dotnet/ as starting points — adapt them to your stack or contribute templates for other ecosystems:
claude-md-conventions.md— MediatR, manual mapping, NSubstitute, Minimal APIs,Result<T>claude-md-conventions-alt.md— Application services (no mediator), AutoMapper, Moq, Controllers,Ardalis.Result, MassTransit
For deeper changes, edit SKILL.md directly. Common modifications:
Change the output path:
The skill saves specs to .claude/specs/{feature-name}.md. If you prefer a different location (e.g., docs/specs/ or specs/), find the output path in the ## Output section and the ## Post-Generation section and update both.
Add or remove phases:
If your team doesn't need the Domain Rules & Exceptions table (Phase 4), or wants an additional phase for security review, edit the phase list. Each phase is a standalone ## Phase N section.
Change the spec template: The output template (the markdown structure at the bottom of SKILL.md) can be modified. For example:
- Remove
## API Contractif your features are all background jobs - Add a
## Security Considerationssection - Add a
## Performance Budgetsection (e.g., "P99 latency under 200ms") - Rename
## Prohibitions (Don'ts)to## Constraintsif your team prefers that language
Customize the reconnaissance: Phase 0 reconnaissance is language-agnostic and adapts to whatever project structure it finds. If you want it to look for specific files or patterns unique to your setup, edit the Phase 0 checklist and update the example questions to reference your libraries.
The examples/ folder contains example specs organized by stack. The bundled examples are .NET/C#, but the skill works with any language — contributions for other stacks are welcome.
| # | Feature | Complexity | Highlights |
|---|---|---|---|
| 01 | Product Rating | Simple | One entity, one endpoint, upsert, cached average. 5 don'ts, flat decision tree, 3 key decisions. |
| 02 | Team Member Invite | Medium | 6 endpoints, token hashing, role hierarchy, async email via domain events. 7 don'ts, two decision trees (send + accept), external integration resilience. |
| 03 | Order Cancellation | Advanced | Financial compliance, payment gateway with circuit breaker, VIP tier logic, multi-branch decision tree, manager review queue. 8 don'ts, complex escalation guardrails, full audit trail. |
All three demonstrate the same spec structure — the difference is how many sections have meaningful content. A simple feature doesn't need complex escalation guardrails; the spec reflects that honestly rather than padding.
theinterviewer/
├── .claude-plugin/
│ └── marketplace.json <- plugin marketplace catalog
├── README.md <- you are here
├── LICENSE
├── examples/
│ └── dotnet/ <- .NET/C# examples (add your stack here!)
│ ├── 01-product-rating.md
│ ├── 02-team-member-invite.md
│ └── 03-order-cancellation.md
├── plugins/
│ └── interview/ <- plugin package (installed via marketplace)
│ ├── .claude-plugin/
│ │ └── plugin.json
│ └── skills/
│ └── interview/
│ ├── SKILL.md
│ └── examples/
│ └── order-cancellation-spec.md
├── skill/
│ ├── SKILL.md <- the interview skill (for manual installation)
│ └── examples/
│ └── order-cancellation-spec.md
└── templates/
└── dotnet/ <- .NET/C# convention templates (add your stack here!)
├── claude-md-conventions.md
└── claude-md-conventions-alt.md
- Don't skip Phase 2 (Don'ts). The highest-value context for AI implementation lives in prohibitions. It's the difference between code that works and code that doesn't break things.
- Name a reference implementation. The single most effective way to get consistent code from Claude is to point it at an existing feature and say "do it like that."
- Resist the urge to start coding mid-plan. The spec is the deliverable. Implementation comes in a fresh session with full context window.
This skill wouldn't exist without ideas and inspiration from the following projects and people:
GitHub spec-kit — The original spec-driven development toolkit. Its multi-phase workflow (specify -> plan -> tasks -> implement), /speckit.clarify for ambiguity resolution, /speckit.analyze for consistency checking, and constitution/principles concept all influenced TheInterviewer's design. The [NEEDS CLARIFICATION] markers and self-consistency audit phase are direct adaptations of spec-kit ideas. The observation that spec traceability IDs (REQ-001, etc.) pollute implementation code is what led to TheInterviewer's anti-spec-pollution approach.
Pimzino/claude-code-spec-workflow — Introduced the steering documents concept (product.md, tech.md, structure.md) that inspired TheInterviewer's convention-based approach. Its approach to sub-agent validation and token-optimized context sharing informed the session separation strategy.
adrianpuiu/specification-document-generator (and the earlier claude-skills-marketplace) — Demonstrated a rigorous six-phase architecture framework with verified research, scope boundaries (in/out/deferred), and validation scripts. The explicit scope boundary section in TheInterviewer specs is a direct adaptation.
obra/superpowers — General-purpose design exploration skill for Claude Code that demonstrated the value of structured, multi-phase AI workflows for planning before implementation.
Issues and PRs welcome. A few ways to contribute:
- Add examples for your stack — create a folder under
examples/(e.g.,examples/java-spring/,examples/typescript-nestjs/) with specs at varying complexity - Improve the skill — better questions, new phases, or sharper reconnaissance heuristics
- Convention templates — add an AGENTS.md / CLAUDE.md convention template for your stack under
templates/
MIT — see LICENSE.