good-spec

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Good Spec

优质规格文档

Addy Osmani의 "Good Spec" 원칙에 기반한 프로젝트 스펙 작성 가이드입니다.

핵심 철학:

고수준 비전 제시 → AI에게 세부사항 위임
모듈식 분할: 한 번에 한 가지 focused 작업
자체 검증: 체크리스트 + LLM-as-a-Judge
스펙 진화: 버전 관리, SPEC.md로 저장

本指南基于Addy Osmani的「Good Spec」原则，是项目规格（Spec）编写的指导手册。

核心哲学:

呈现高水准愿景 → 将细节交由AI处理
模块化拆分：一次专注完成一项任务
自我验证：检查表 + LLM-as-a-Judge
规格演进：版本管理，以SPEC.md形式保存

6가지 핵심 영역

6个核心领域

영역	해결하는 질문	핵심 요소
Commands	"어떻게 실행하나요?"	개발/테스트/빌드 명령어 + 결과
Testing	"어떻게 검증하나요?"	프레임워크 + 커버리지 기준
Project Structure	"어디에 작성하나요?"	디렉토리 역할 + 파일 명명규칙
Code Style	"어떻게 작성하나요?"	✅/❌ 예시 (설명 < 예시)
Git Workflow	"어떻게 협업하나요?"	브랜치/커밋/PR 규칙
Boundaries	"무엇을 하면/말아야 하나요?"	Always/Ask/Never 3단계

상세 작성 가이드:

resources/01-spec-template.md

복사용 템플릿:

templates/SPEC-template.md

领域	解决的问题	核心要素
Commands	"如何执行？"	开发/测试/构建命令 + 结果
Testing	"如何验证？"	框架 + 覆盖率标准
Project Structure	"在哪里编写？"	目录作用 + 文件命名规则
Code Style	"如何编写？"	✅/❌示例（说明 < 示例）
Git Workflow	"如何协作？"	分支/提交/PR规则
Boundaries	"应该做/不应该做什么？"	Always/Ask/Never三级划分

详细编写指南:

resources/01-spec-template.md

可直接复制的模板:

templates/SPEC-template.md

3단계 경계 시스템

三级边界系统

스펙의 가장 중요한 부분은 경계 정의입니다:

레벨	의미	예시
✅ Always	항상 실행	테스트 실행, 컨벤션 준수, 린트 검사
⚠️ Ask First	승인 필요	DB 스키마 변경, 의존성 추가, API 변경
🚫 Never	절대 금지	시크릿 커밋, vendor 폴더 편집, --force 옵션

规格文档中最重要的部分是边界定义:

级别	含义	示例
✅ Always	必须执行	运行测试、遵循规范、代码检查
⚠️ Ask First	需要审批	修改数据库Schema、添加依赖、变更API
🚫 Never	绝对禁止	提交密钥文件、编辑vendor目录、使用--force选项

Phase 1: Discovery (요구사항 파악)

阶段1：需求调研（明确需求）

새 프로젝트 또는 기존 프로젝트 스펙 작성 시:

프로젝트 컨텍스트 파악
- 프로젝트 목적과 범위
- 기술 스택 확인
- 팀 구성 (개발자 수, 역할)
- 기존 문서 검토 (README.md, package.json 등)
현재 상태 분석
- 기존 SPEC.md 또는 CLAUDE.md 존재 여부
- 프로젝트 구조 파악 (
```
Glob
```
  ,
```
ls
```
  활용)
- 주요 명령어 확인 (package.json scripts, Makefile 등)
핵심 질문 도출
- "어떤 명령어로 테스트하나요?"
- "코드 스타일 가이드가 있나요?"
- "AI가 수정하면 안 되는 파일이 있나요?"
사용자 확인
- 파악한 컨텍스트 공유
- 누락된 정보 확인
- Phase 2로 진행 동의

在编写新项目或现有项目的规格文档时：

了解项目背景
- 项目目标与范围
- 确认技术栈
- 团队构成（开发人员数量、角色）
- 审阅现有文档（README.md、package.json等）
分析当前状态
- 是否存在现有SPEC.md或CLAUDE.md
- 了解项目结构（使用
```
Glob
```
  、
```
ls
```
  命令）
- 确认核心命令（package.json scripts、Makefile等）
提炼核心问题
- "用什么命令执行测试？"
- "是否有代码风格指南？"
- "AI不应修改哪些文件？"
与用户确认
- 共享已掌握的背景信息
- 确认缺失的信息
- 获得进入阶段2的许可

중요 원칙

重要原则

예시 우선: 설명 3단락 < 예시 1개
구체성: "적절히" "가능하면" 금지, 구체적 기준 명시
경계가 핵심: Always/Ask/Never 명확히 구분
실행 가능: 모든 명령어 검증 가능
진화: 스펙은 살아있는 문서, 정기 업데이트

示例优先：3段说明不如1个示例
具体化：禁止使用"适当""尽可能"等表述，明确具体标准
边界是核心：清晰划分Always/Ask/Never
可执行：所有命令必须可验证
持续演进：规格是活文档，定期更新

Phase 2: Formulation (스펙 작성)

阶段2：规格编写

6개 영역을 순서대로 작성합니다. 각 영역의 상세 예시와 작성 가이드는

resources/01-spec-template.md

를 참조하세요.

按顺序完成6个领域的编写。各领域的详细示例与编写指南可参考

resources/01-spec-template.md

。

영역 1: Commands

领域1：Commands

개발/테스트/빌드 명령어 나열
주석으로 포트, 경로, 기대 결과 명시
최소 요구사항 기재 (예: coverage 80%)

列出开发/测试/构建命令
用注释说明端口、路径、预期结果
注明最低要求（例如：覆盖率80%）

영역 2: Testing

领域2：Testing

프레임워크 명시 (Jest, Vitest, Playwright 등)
테스트 파일 위치 패턴 (
```
src/**/*.test.ts
```
)
커버리지 기대치 (전체, critical paths 구분)
테스트 명명 규칙

明确测试框架（Jest、Vitest、Playwright等）
测试文件位置模式（
```
src/**/*.test.ts
```
）
覆盖率预期（整体、关键路径区分）
测试命名规则

영역 3: Project Structure

领域3：Project Structure

주요 디렉토리만 (3-7개)
각 디렉토리 역할 주석
자동 생성 폴더 표시 (
```
dist/
```
,
```
node_modules/
```
)

仅保留核心目录（3-7个）
为每个目录添加作用注释
标注自动生成的目录（
```
dist/
```
、
```
node_modules/
```
）

영역 4: Code Style

领域4：Code Style

설명 3단락보다 예시 1개가 효과적
✅/❌ 비교 형식 필수
실제 프로젝트 코드에서 추출
함수, 컴포넌트, 에러 처리 등 카테고리별 예시

3段说明不如1个示例有效
必须包含✅/❌对比格式
从实际项目代码中提取示例
按函数、组件、错误处理等类别提供示例

영역 5: Git Workflow

领域5：Git Workflow

브랜치 명명 패턴 (
```
feat/
```
,
```
fix/
```
,
```
refactor/
```
)
커밋 메시지 형식 (Conventional Commits)
PR 체크리스트
머지 전략 (Squash/Merge/Rebase)

分支命名模式（
```
feat/
```
、
```
fix/
```
、
```
refactor/
```
）
提交消息格式（Conventional Commits）
PR检查清单
合并策略（Squash/Merge/Rebase）

영역 6: Boundaries (가장 중요!)

领域6：Boundaries（最重要！）

3단계 경계 시스템 (상단 테이블 참조) 적용:

3단계 명확히 구분 (Always/Ask First/Never)
구체적 파일/명령어 명시 ("중요한 파일" ❌ → "src/config/*.json" ✅)
Never 항목은 보안/안정성 중심

应用三级边界系统（参考上方表格）:

清晰划分三级边界（Always/Ask First/Never）
明确具体文件/命令（禁止"重要文件"，需改为"src/config/*.json"）
Never条目以安全/稳定性为核心

Phase 3: Validation (검증)

阶段3：规格验证

스펙 작성 후 자체 검증:

完成规格编写后进行自我验证:

체크리스트

检查清单

AI Red Flags 🚨

AI警示信号 🚨

다음 징후 발견 시 즉시 중단하고 Phase 2로 돌아가기:

🚨 Boundaries 없음 - 스펙의 가장 중요한 부분 누락
🚨 설명만 있고 예시 없음 - Code Style은 반드시 코드 예시 포함
🚨 실행 불가능한 명령어 - 모든 Commands는 검증 가능해야 함
🚨 모호한 Boundaries - "중요한 파일 수정 금지" ❌ → "src/config/*.json 수정 금지" ✅

发现以下迹象时，立即停止并返回阶段2:

🚨 缺失Boundaries - 遗漏了规格中最重要的部分
🚨 仅有说明无示例 - Code Style必须包含代码示例
🚨 无法执行的命令 - 所有Commands必须可验证
🚨 模糊的Boundaries - "禁止修改重要文件" ❌ → "禁止修改src/config/*.json" ✅

LLM-as-a-Judge (선택)

LLM-as-a-Judge（可选）

다음 스펙을 검토하고 개선점을 제안해주세요:
1. 누락된 정보가 있나요?
2. 모호한 표현이 있나요?
3. 예시가 충분한가요?

请审阅以下规格并提出改进建议:
1. 是否存在信息缺失？
2. 是否有模糊表述？
3. 示例是否充分？

Phase 4: Evolution (스펙 진화)

阶段4：规格演进

스펙은 프로젝트와 함께 진화해야 합니다:

버전 관리

markdown

# SPEC.md
Version: 2.1.0
Last Updated: 2026-01-19

변경 이력

markdown

## Changelog

### 2.1.0 (2026-01-19)
- Added E2E testing with Playwright
- Updated Node.js version to 20.x

### 2.0.0 (2025-12-01)
- Migrated to TypeScript
- Introduced strict boundary rules

정기 리뷰
- 월 1회 또는 major change 시
- 새 팀원 온보딩 후 피드백 반영
- AI 사용 중 반복되는 문제 발견 시
스펙 개선 트리거
- AI가 Ask First를 자주 위반 → Never로 승격
- 새로운 도구 도입 (예: 새 테스트 프레임워크)
- 팀 컨벤션 변경

规格需随项目一同演进:

版本管理

markdown

# SPEC.md
Version: 2.1.0
Last Updated: 2026-01-19

变更记录

markdown

## 变更日志

### 2.1.0 (2026-01-19)
- 新增Playwright端到端测试
- 将Node.js版本更新至20.x

### 2.0.0 (2025-12-01)
- 迁移至TypeScript
- 引入严格的边界规则

定期审阅
- 每月1次或重大变更时进行
- 新成员入职后整合反馈
- 发现AI使用中反复出现的问题时
规格改进触发条件
- AI频繁违反Ask First规则 → 升级为Never
- 引入新工具（例如：新测试框架）
- 团队规范变更

Examples

示例

신규 프로젝트 스펙 작성

新项目规格编写示例

User: "새 Next.js 프로젝트 스펙 작성해줘"

AI 명령 흐름:
1. Glob "package.json" + Read package.json (기술 스택 파악)
2. Glob "**/*" (프로젝트 구조 파악)
3. Phase 1: 사용자에게 컨텍스트 확인
   - "Next.js 14, TypeScript, Tailwind CSS 사용 중이시네요"
   - "테스트 프레임워크는 어떤 걸 사용하시나요? (Jest/Vitest)"
4. Phase 2: 6개 영역 작성
   - Commands: package.json scripts 기반
   - Testing: 답변받은 프레임워크 기반
   - Project Structure: 현재 디렉토리 구조 반영
   - Code Style: Next.js 모범 사례 + TypeScript
   - Git Workflow: Conventional Commits
   - Boundaries: Next.js 특수 파일 (next.config.js 등) 보호
5. Phase 3: 검증 체크리스트 확인
6. Write SPEC.md

用户：“请帮我编写新Next.js项目的规格”

AI执行流程:
1. 执行Glob "package.json" 并读取package.json（了解技术栈）
2. 执行Glob "**/*"（了解项目结构）
3. 阶段1：与用户确认背景信息
   - “您当前使用的是Next.js 14、TypeScript、Tailwind CSS”
   - “您使用的测试框架是什么？（Jest/Vitest）”
4. 阶段2：编写6个领域内容
   - Commands：基于package.json scripts
   - Testing：基于用户回复的框架
   - Project Structure：基于当前目录结构
   - Code Style：Next.js最佳实践 + TypeScript规范
   - Git Workflow：采用Conventional Commits
   - Boundaries：保护Next.js特殊文件（如next.config.js等）
5. 阶段3：检查验证清单
6. 编写SPEC.md

기존 프로젝트 스펙 개선

现有项目规格改进示例

User: "SPEC.md에 E2E 테스트 정책 추가해줘"

AI 명령 흐름:
1. Read SPEC.md (현재 스펙 파악)
2. Phase 1: 현재 E2E 테스트 상태 확인
   - "Playwright 사용하시나요, Cypress인가요?"
   - "E2E 테스트 파일은 어디에 위치하나요?"
3. Phase 2: 관련 영역 업데이트
   - Testing 영역: E2E 프레임워크, 파일 위치, 커버리지 추가
   - Commands 영역: E2E 실행 명령 추가 (`npm run test:e2e`)
   - Boundaries: E2E 테스트 Always 규칙 추가
4. Phase 3: 검증
5. Phase 4: 버전 업데이트 (1.0.0 → 1.1.0), Changelog 추가
6. Edit SPEC.md

用户：“请在SPEC.md中添加端到端测试策略”

AI执行流程:
1. 读取SPEC.md（了解当前规格）
2. 阶段1：确认当前端到端测试状态
   - “您使用的是Playwright还是Cypress？”
   - “端到端测试文件存放在哪里？”
3. 阶段2：更新相关领域内容
   - Testing领域：添加端到端测试框架、文件位置、覆盖率要求
   - Commands领域：添加端到端测试执行命令（`npm run test:e2e`）
   - Boundaries：添加端到端测试Always规则
4. 阶段3：验证
5. 阶段4：更新版本（1.0.0 → 1.1.0），添加变更日志
6. 编辑SPEC.md

Boundaries 강화

边界规则强化示例

User: "AI가 자꾸 .env 파일 수정하려고 해"

AI 명령 흐름:
1. Read SPEC.md
2. Phase 1: 현재 Boundaries 확인
3. Phase 2: Never 섹션에 명시적 추가

🚫 Never (절대 금지)

❌ Commit or edit
```
.env
```
files (use
```
.env.example
```
for templates)
❌ Hardcode API keys, passwords, tokens

4. Phase 3: 검증
5. Edit SPEC.md
6. 사용자에게 변경사항 공유

---

用户：“AI总是试图修改.env文件”

AI执行流程:
1. 读取SPEC.md
2. 阶段1：检查当前Boundaries规则
3. 阶段2：在Never部分明确添加

🚫 Never（绝对禁止）

❌ 提交或编辑
```
.env
```
文件（使用
```
.env.example
```
作为模板）
❌ 硬编码API密钥、密码、令牌

4. 阶段3：验证
5. 编辑SPEC.md
6. 向用户告知变更内容

---

Technical Details

技术细节

상세 템플릿

详细模板

```
resources/01-spec-template.md
```
: 6개 영역 상세 설명 + 작성 예시
```
templates/SPEC-template.md
```
: 복사해서 바로 사용 가능한 템플릿

```
resources/01-spec-template.md
```
：6个领域的详细说明 + 编写示例
```
templates/SPEC-template.md
```
：可直接复制使用的模板

참조 리소스

参考资源

Addy Osmani의 원본 가이드: https://addyosmani.com/blog/good-spec/
ldoc skill: 요구사항 문서화와 연계
bdd-practices: Testing 영역 작성 시 시나리오 활용

Addy Osmani的原始指南：https://addyosmani.com/blog/good-spec/
ldoc skill：与需求文档化联动
bdd-practices：编写Testing领域时可参考场景