Create a New Feature Spec with Claude Code

How to Create a New Feature Spec with Claude Code

This guide will walk you through the process of using Claude Code’s `spec` command to generate a detailed specification for a new feature in your project. You’ll learn how to define feature requirements, review generated specifications, and understand the components of a well-defined spec file.

Overview

In this tutorial, you will learn how to leverage Claude Code to automatically generate a comprehensive specification for a new feature. We will cover how to initiate the spec generation process using a prompt, understand the structure and content of the generated spec file, and review the functional requirements, edge cases, acceptance criteria, open questions, and testing guidelines provided by Claude Code. This process helps ensure all aspects of a new feature are considered before implementation begins.

Prerequisites

• A project set up with Claude Code.
• The `spec` command available in your Claude Code session. (You may need to exit and resume your session for new commands to appear).

Steps

1. Initiate Spec Generation

   Begin by typing the `spec` command in your Claude Code chat interface. This command signals Claude Code to prepare for generating a new feature specification.

2. Provide a Detailed Prompt

   Following the `spec` command, enter a clear and concise prompt describing the feature you want to spec. Include all essential elements and constraints. For example:

   Let's spec the authentication forms on the login and signup pages. They need email and password fields, a hide password icon, and a submit button in brackets, signup, login. The form should only log details to the console for now when they are submitted. We should be able to easily switch between the two forms.

   Tip: While you can manually add relevant files as context using the ‘@’ symbol, for small projects or when the relevant files are easily discoverable, Claude Code can often infer context effectively without explicit additions.

3. Execute and Review Initial Setup

   Press Enter to submit your prompt. Claude Code will first check your current Git branch to ensure there are no uncommitted changes. If the branch is clean, it will propose a feature title, a feature slug (used for branch naming), and a new branch name following the pattern: `Claude-FeatureName`. It will then automatically switch to this new branch.

   Expert Note: Toggling on ‘auto accepts’ can streamline this process, allowing Claude Code to proceed with branch switching and file creation automatically once the spec is generated.

4. Examine the Generated Spec File

   Claude Code will create a new file within your project’s `specs` folder. Open this file to review the generated specification. The file typically includes:

   • Title: The feature’s title.
   • Branch Name: The Git branch created for this feature.
   • Summary: A rephrased version of your initial prompt.
   • Functional Requirements: Detailed descriptions of the features and components to be implemented (e.g., input fields, buttons, specific behaviors like password visibility toggling).
   • Possible Edge Cases: Potential scenarios and issues to consider during development (e.g., empty fields, rapid toggling of visibility, invalid input).
   • Acceptance Criteria: Specific conditions that must be met for the feature to be considered complete and acceptable (e.g., fields render correctly, toggle icon functions as expected).
   • Open Questions: Queries from Claude Code to clarify ambiguities or seek further input on design decisions (e.g., validation rules, password length, input persistence, additional features like ‘remember me’ or ‘forgot password’).
   • Testing Guidelines: Recommendations for creating tests for the feature, often specifying a location for test files (e.g., within a `tests` folder).

   Warning: Take your time to thoroughly read and understand every section of the generated spec. Do not rush this review process.

5. Address Open Questions

   Carefully consider the ‘Open Questions’ section. For each question, decide on the desired behavior or constraint and provide your answer. This step is crucial for clarifying requirements and ensuring the final implementation aligns with your expectations.

   For example, when asked about email validation, you might specify ‘light validation’ on the front end. For password length, you might decide to let the back end handle it later, responding with ‘no’ for front-end enforcement. Similarly, decide on requirements like input persistence or the inclusion of links like ‘forgot password’.

6. Refine and Finalize the Spec

   Based on your review and answers to the open questions, edit the spec file as needed. Ensure all requirements are accurately captured and that the specification is clear, unambiguous, and complete. This iterative refinement ensures you have a solid plan before moving to implementation.

   Expert Note: While Claude Code generates a strong starting point, your active participation in reviewing and refining the spec is key to a successful development process. Spend 5-10 minutes or more scrutinizing the details.

Next Steps

Once you are satisfied with the generated and refined spec file, the next logical step is to create a detailed technical plan for implementing the feature. This is typically done using Claude Code’s ‘plan’ mode, which will be covered in subsequent guides.

Source: Spec Driven Workflow with Claude Code #2 – Creating a New Spec (YouTube)