[GitHub Global] Translate Vibe Coding 零基础教程/10 编程工具/工具实战/Spec-kit：规范驱动开发框架.md to en
This commit is contained in:
yupi-translate-app[bot]
committed by
GitHub
GitHub
parent
989cd551bc
commit
8003007a59
@@ -0,0 +1,237 @@
|
||||
# Spec-kit: Specification-Driven Development Framework
|
||||
|
||||
> Enable AI to develop projects following professional processes
|
||||
|
||||
Hello, I'm programmer Yupi.
|
||||
|
||||
In previous articles, we learned how to quickly generate code using AI. But you might have noticed that AI sometimes "writes as it thinks," resulting in code that may not meet expectations or projects that fall apart halfway through.
|
||||
|
||||
Is there a way to make AI develop projects following professional processes?
|
||||
|
||||
In this article, I'll introduce **Spec-kit**, a specification-driven development framework launched by GitHub, which enables AI to work like a professional programmer.
|
||||
|
||||
Let's get started!
|
||||
|
||||
|
||||
|
||||
## What is Spec-kit?
|
||||
|
||||
[Spec-kit](https://github.com/github/spec-kit) is a specification-driven development (SDD) framework launched by GitHub.
|
||||
|
||||
What is specification-driven development?
|
||||
|
||||
The traditional development process is: write whatever comes to mind, make changes as you go, and document it later. This often leads to unclear requirements and mismatched code and documentation.
|
||||
|
||||
Specification-driven development takes the opposite approach: **first write the requirements into a specification document and treat it as the single source of truth for the code**. You can think of the specification document as "legal text," which contains detailed requirement descriptions, system designs, and interface definitions. AI must strictly adhere to these texts to generate code, ensuring the output fully meets expectations.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
## Quick Start with Spec-kit
|
||||
|
||||
Let me walk you through a practical example to quickly get started with Spec-kit.
|
||||
|
||||
### 1. Install Spec-kit
|
||||
|
||||
First, open the terminal and use the uvx command to directly install and run the Specify tool, and initialize a project:
|
||||
|
||||
```bash
|
||||
uvx --from git+https://github.com/github/spec-kit.git specify init my-project
|
||||
```
|
||||
|
||||
|
||||
|
||||
Select the AI programming tool you use. Spec-kit supports almost all mainstream programming tools like Claude Code and GitHub Copilot. Here, I choose Claude Code:
|
||||
|
||||
|
||||
|
||||
Choose the script type based on your operating system. Select the bottom option for Windows and the top option for others:
|
||||
|
||||
|
||||
|
||||
After executing this command, a `my-project` folder will be created in the current directory:
|
||||
|
||||
|
||||
|
||||
The folder contains these core files:
|
||||
|
||||
- `.specify/memory/constitution.md`: Basic guidelines and conventions for the project
|
||||
- `.specify/scripts/`: Some executable scripts
|
||||
- `.specify/templates/`: Template files
|
||||
- `.claude/commands/`: Defines a set of built-in slash commands that you can directly call in AI programming tools
|
||||
|
||||
|
||||
|
||||
The initialization program also provides some guidance on how to use these commands to develop the project.
|
||||
|
||||
|
||||
|
||||
Open this project folder with Claude Code, and you can use the defined commands in the conversation.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
### 2. Standardized Development Process
|
||||
|
||||
Next is the standardized development process, as outlined in the [official documentation](https://github.com/github/spec-kit), mainly divided into 7 steps:
|
||||
|
||||
#### 1) Constitution: Define Project Guidelines
|
||||
|
||||
Run the `/speckit.constitution` command to define the project's basic principles, code standards, performance criteria, etc. This is the project's "constitution," and all subsequent development must adhere to it.
|
||||
|
||||
For example:
|
||||
|
||||
```markdown
|
||||
/speckit.constitution Prohibit using blue-purple gradient UI styles
|
||||
```
|
||||
|
||||
💡 If you're working on a Chinese project, it's best to explicitly tell AI "the entire website uses Chinese" when defining the project guidelines.
|
||||
|
||||
|
||||
|
||||
AI updated the project guidelines document:
|
||||
|
||||
|
||||
|
||||
It's recommended to commit a version with Git at each step, so you can roll back if something goes wrong and easily see the changes made at each step.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
#### 2) Specify: Write Functional Specifications
|
||||
|
||||
Run the `/speckit.specify` command to describe what functionality to implement, why, and what the user needs are. For example:
|
||||
|
||||
```markdown
|
||||
/speckit.specify I want to create a [website that reminds me to drink water automatically]
|
||||
```
|
||||
|
||||
|
||||
|
||||
AI created a new Git branch for this requirement to prevent contaminating the existing project. Under this branch, a requirement specification document (spec.md) and a requirement checklist document (requirements.md) were created.
|
||||
|
||||
|
||||
|
||||
The requirement specification document is very detailed and includes edge test cases to handle various possible user actions.
|
||||
|
||||
|
||||
|
||||
The requirement checklist document records AI's understanding of the requirements, with checkmarks indicating AI's confirmation:
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
#### 3) Clarify: Clarify Ambiguities (Optional)
|
||||
|
||||
If you find some items in the requirement checklist document are not checked, you need to use the Clarify command to guide AI in further clarifying the requirements until all items are checked.
|
||||
|
||||
Run the `/speckit.clarify` command, and AI will ask structured questions for you to answer, helping you fill in the gaps in the requirements, such as edge cases and error handling.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
#### 4) Plan: Develop Technical Solutions
|
||||
|
||||
Run the `/speckit.plan` command to let AI decide on the technology stack, system architecture, data models, API interfaces, etc.
|
||||
|
||||
|
||||
|
||||
The technical solution is complete, and a bunch of documents were generated. Let's briefly understand them:
|
||||
|
||||
- CLAUDE.md Project Development Guide, recording the technology stack and project structure to guide Claude Code on how to proceed with development
|
||||
- quickstart.md Quick Start Guide, containing 6 implementation phases and deployment plans
|
||||
- plan.md Implementation Plan, defining a pure client-side architecture, storage strategy, constitution compliance checks, etc.
|
||||
- data-model.md Data Model Design, defining 4 core entities (reminder settings, water log, daily progress, history) and storage structure
|
||||
- research.md Technical Research Document, recording 8 key technical decisions
|
||||
- contracts/api-contract.md API Interface Document
|
||||
|
||||
|
||||
|
||||
Next, we can prepare for development implementation.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
#### 5) Tasks: Break Down Tasks
|
||||
|
||||
Run the `/speckit.tasks` command to break down the plan into executable task lists, annotating dependencies and priorities.
|
||||
|
||||
|
||||
|
||||
A task list document was generated, clearly outlining what to do at each step:
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
#### 6) Analyze: Analyze and Check (Optional)
|
||||
|
||||
Run the `/speckit.analyze` command to check if the specifications, plans, and tasks are complete and consistent, identifying design flaws early.
|
||||
|
||||
|
||||
|
||||
As you can see, AI didn't find any issues and encouraged me to proceed confidently. Feels great!
|
||||
|
||||
|
||||
|
||||
#### 7) Implement: Execute Implementation
|
||||
|
||||
Finally, run the `/speckit.implement` command to let AI generate code according to the task list.
|
||||
|
||||
|
||||
|
||||
Mission accomplished, let's see the results~
|
||||
|
||||
|
||||
|
||||
Since I never mentioned using Chinese output, the website content is in English, but I think the effect is quite good.
|
||||
|
||||
|
||||
|
||||
## Pros and Cons of Spec-kit
|
||||
|
||||
By now, we've learned how to develop a complete project using Spec-kit. Let's review the full process:
|
||||
|
||||
|
||||
|
||||
Even without Spec-kit, we can manually follow these steps when developing a complete project.
|
||||
|
||||
The biggest advantage of this model is **alignment**. Everyone works based on the same clear specification document, ensuring a high level of understanding of the requirements, reducing misunderstandings in communication, and ensuring code quality.
|
||||
|
||||
However, the downside is also obvious. For small projects, which could be completed in minutes by directly writing code, following this process might take about half an hour!
|
||||
|
||||
So this process is more suitable for teams starting a complete new project from scratch. Although the process is slower than directly writing code, it significantly reduces the risk of rework, making it more efficient in the long run.
|
||||
|
||||
|
||||
|
||||
## Final Thoughts
|
||||
|
||||
By now, I believe you have a basic understanding of Spec-kit.
|
||||
|
||||
**Spec-kit is not a panacea, but in the right scenarios, it can significantly improve project quality.**
|
||||
|
||||
If you're working on a large project, need team collaboration, or have high code quality requirements, then you can try Spec-kit. But if you're just writing a simple script or quickly validating an idea, directly generating code with AI will be faster.
|
||||
|
||||
Choosing the right tool can make your work more efficient.
|
||||
|
||||
In upcoming articles, I'll continue to introduce other standardized development tools to help you find the most suitable development approach.
|
||||
|
||||
|
||||
|
||||
## Recommended Resources
|
||||
|
||||
1) Yupi AI Navigation Website: [AI Resource Collection, Latest AI News, Free AI Tutorials](https://ai.codefather.cn)
|
||||
|
||||
2) Programming Navigation Learning Circle: [Learning Paths, Programming Tutorials, Practical Projects, Job Hunting Guide, Q&A](https://www.codefather.cn)
|
||||
|
||||
3) Programmer Interview Cheatsheet: [Internship/Campus/Social Recruitment High-Frequency Exam Points, Enterprise Real Questions Analysis](https://www.mianshiya.com)
|
||||
|
||||
4) Programmer Resume Writing Tool: [Professional Templates, Rich Examples, Direct to Interview](https://www.laoyujianli.com)
|
||||
|
||||
5) 1-on-1 Mock Interview: [Essential for Internship/Campus/Social Recruitment Interviews to Get Offers](https://ai.mianshiya.com)
|
||||
Reference in New Issue
Block a user