Back to Details

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：需求调研（明确需求）

새 프로젝트 또는 기존 프로젝트 스펙 작성 시:
  1. 프로젝트 컨텍스트 파악
    • 프로젝트 목적과 범위
    • 기술 스택 확인
    • 팀 구성 (개발자 수, 역할)
    • 기존 문서 검토 (README.md, package.json 등)
  2. 현재 상태 분석
    • 기존 SPEC.md 또는 CLAUDE.md 존재 여부
    • 프로젝트 구조 파악 (
      Glob
      , 
      ls
      활용)
    • 주요 명령어 확인 (package.json scripts, Makefile 등)
  3. 핵심 질문 도출
    • "어떤 명령어로 테스트하나요?"
    • "코드 스타일 가이드가 있나요?"
    • "AI가 수정하면 안 되는 파일이 있나요?"
  4. 사용자 확인
    • 파악한 컨텍스트 공유
    • 누락된 정보 확인
    • Phase 2로 진행 동의
在编写新项目或现有项目的规格文档时：
  1. 了解项目背景
    • 项目目标与范围
    • 确认技术栈
    • 团队构成（开发人员数量、角色）
    • 审阅现有文档（README.md、package.json等）
  2. 分析当前状态
    • 是否存在现有SPEC.md或CLAUDE.md
    • 了解项目结构（使用
      Glob
      、
      ls
      命令）
    • 确认核心命令（package.json scripts、Makefile等）
  3. 提炼核心问题
    • "用什么命令执行测试？"
    • "是否有代码风格指南？"
    • "AI不应修改哪些文件？"
  4. 与用户确认
    • 共享已掌握的背景信息
    • 确认缺失的信息
    • 获得进入阶段2的许可

중요 원칙

重要原则

  1. 예시 우선: 설명 3단락 < 예시 1개
  2. 구체성: "적절히" "가능하면" 금지, 구체적 기준 명시
  3. 경계가 핵심: Always/Ask/Never 명확히 구분
  4. 실행 가능: 모든 명령어 검증 가능
  5. 진화: 스펙은 살아있는 문서, 정기 업데이트
  1. 示例优先：3段说明不如1个示例
  2. 具体化：禁止使用"适当""尽可能"等表述，明确具体标准
  3. 边界是核心：清晰划分Always/Ask/Never
  4. 可执行：所有命令必须可验证
  5. 持续演进：规格是活文档，定期更新

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：规格验证

스펙 작성 후 자체 검증:
完成规格编写后进行自我验证:

체크리스트

检查清单

  • 6개 영역 모두 작성됨
  • 각 명령어에 설명 포함 (포트, 경로, 결과)
  • Code Style에 ✅/❌ 예시 포함
  • Boundaries 3단계 (Always/Ask/Never) 명확히 구분
  • 모든 명령어 실제 실행 가능
  • 모호한 표현 없음 ("적절히", "가능하면" 금지)
  • 6个领域全部完成编写
  • 每个命令都包含说明（端口、路径、结果）
  • Code Style包含✅/❌示例
  • Boundaries清晰划分三级（Always/Ask/Never）
  • 所有命令均可实际执行
  • 无模糊表述（禁止"适当""尽可能"）

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：规格演进

스펙은 프로젝트와 함께 진화해야 합니다:
  1. 버전 관리
    markdown
    # SPEC.md
Version: 2.1.0
Last Updated: 2026-01-19
  2. 변경 이력
    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
  3. 정기 리뷰
    • 월 1회 또는 major change 시
    • 새 팀원 온보딩 후 피드백 반영
    • AI 사용 중 반복되는 문제 발견 시
  4. 스펙 개선 트리거
    • AI가 Ask First를 자주 위반 → Never로 승격
    • 새로운 도구 도입 (예: 새 테스트 프레임워크)
    • 팀 컨벤션 변경
规格需随项目一同演进:
  1. 版本管理
    markdown
    # SPEC.md
Version: 2.1.0
Last Updated: 2026-01-19
  2. 变更记录
    markdown
    ## 变更日志

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

### 2.0.0 (2025-12-01)
- 迁移至TypeScript
- 引入严格的边界规则
  3. 定期审阅
    • 每月1次或重大变更时进行
    • 新成员入职后整合反馈
    • 发现AI使用中反复出现的问题时
  4. 规格改进触发条件
    • 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
    ：可直接复制使用的模板

참조 리소스

参考资源