# [PROJECT_NAME] Constitution
<!-- Example: Spec Constitution, TaskFlow Constitution, etc. -->
## Core Principles
### [PRINCIPLE_1_NAME]
<!-- Example: I. Library-First -->
[PRINCIPLE_1_DESCRIPTION]
<!-- Example: Every feature starts as a standalone library; Libraries must be self-contained, independently testable, documented; Clear purpose required - no organizational-only libraries -->
### [PRINCIPLE_2_NAME]
<!-- Example: II. CLI Interface -->
[PRINCIPLE_2_DESCRIPTION]
<!-- Example: Every library exposes functionality via CLI; Text in/out protocol: stdin/args → stdout, errors → stderr; Support JSON + human-readable formats -->
### [PRINCIPLE_3_NAME]
<!-- Example: III. Test-First (NON-NEGOTIABLE) -->
[PRINCIPLE_3_DESCRIPTION]
<!-- Example: TDD mandatory: Tests written → User approved → Tests fail → Then implement; Red-Green-Refactor cycle strictly enforced -->
### [PRINCIPLE_4_NAME]
<!-- Example: IV. Integration Testing -->
[PRINCIPLE_4_DESCRIPTION]
<!-- Example: Focus areas requiring integration tests: New library contract tests, Contract changes, Inter-service communication, Shared schemas -->
### [PRINCIPLE_5_NAME]
<!-- Example: V. Observability, VI. Versioning & Breaking Changes, VII. Simplicity -->
[PRINCIPLE_5_DESCRIPTION]
<!-- Example: Text I/O ensures debuggability; Structured logging required; Or: MAJOR.MINOR.BUILD format; Or: Start simple, YAGNI principles -->
## [SECTION_2_NAME]
<!-- Example: Additional Constraints, Security Requirements, Performance Standards, etc. -->
[SECTION_2_CONTENT]
<!-- Example: Technology stack requirements, compliance standards, deployment policies, etc. -->
## [SECTION_3_NAME]
<!-- Example: Development Workflow, Review Process, Quality Gates, etc. -->
[SECTION_3_CONTENT]
<!-- Example: Code review requirements, testing gates, deployment approval process, etc. -->
## Governance
<!-- Example: Constitution supersedes all other practices; Amendments require documentation, approval, migration plan -->
[GOVERNANCE_RULES]
<!-- Example: All PRs/reviews must verify compliance; Complexity must be justified; Use [GUIDANCE_FILE] for runtime development guidance -->
**Version**: [CONSTITUTION_VERSION] | **Ratified**: [RATIFICATION_DATE] | **Last Amended**: [LAST_AMENDED_DATE]
<!-- Example: Version: 2.1.1 | Ratified: 2025-06-13 | Last Amended: 2025-07-16 -->
1. 문서 제목
# [PROJECT_NAME] Constitution이 줄은 문서의 최상위 제목입니다.
[PROJECT_NAME]은 실제 프로젝트 이름으로 바꿔야 하는 자리표시자입니다. 예를 들어 todo 앱 프로젝트라면 다음과 같이 수정할 수 있습니다.
# TodoList App ConstitutionConstitution은 말 그대로 “헌법”이라는 뜻입니다. 여기서는 프로젝트를 개발할 때 반드시 지켜야 하는 최상위 원칙 문서라는 의미로 사용됩니다.
블로그에서는 다음처럼 설명할 수 있습니다.
이 문서는 프로젝트의 개발 방향과 의사결정 기준을 정의하는 최상위 규칙 문서이다. 코드 스타일, 테스트 기준, 리뷰 방식, 품질 원칙 등은 이 constitution을 기준으로 판단된다.
2. 예시 주석
<!-- Example: Spec Constitution, TaskFlow Constitution, etc. -->이 줄은 HTML 주석입니다.
Markdown 문서 안에서 <!-- ... --> 형태로 작성된 내용은 일반적으로 화면에 표시되지 않습니다. 문서를 작성하는 사람에게 참고용 안내를 제공하기 위한 주석입니다.
여기서는 constitution 제목을 어떻게 작성하면 되는지 예시를 보여줍니다.
예를 들어 다음과 같은 이름을 사용할 수 있다는 뜻입니다.
# Spec Constitution
# TaskFlow Constitution
# TodoList App Constitution즉, 이 줄은 실제 문서 내용이라기보다 작성자를 위한 가이드입니다.
Core Principles 섹션
3. 핵심 원칙 섹션 제목
## Core Principles이 줄은 “핵심 원칙” 섹션을 시작합니다.
Core Principles는 프로젝트 개발에서 가장 중요하게 지켜야 할 기본 원칙들을 모아두는 영역입니다.
예를 들어 다음과 같은 원칙들이 들어갈 수 있습니다.
- 테스트 우선 개발
- 단순성 우선
- 보안 우선
- 문서와 코드의 일치
- 최소 의존성
- 접근성 고려
- 성능 기준 준수
이 섹션은 constitution 문서의 중심부입니다. 이후에 나오는 Principle 1부터 Principle 5까지는 모두 이 핵심 원칙에 해당합니다.
Principle 1
4. 첫 번째 원칙 제목
### [PRINCIPLE_1_NAME]이 줄은 첫 번째 핵심 원칙의 제목입니다.
[PRINCIPLE_1_NAME]은 자리표시자이므로 실제 원칙 이름으로 바꿔야 합니다.
예를 들어 다음과 같이 작성할 수 있습니다.
### I. Simplicity First또는 한국어와 영어를 병기하면 다음처럼 쓸 수 있습니다.
### I. 단순성 우선 / Simplicity First여기서 ###는 Markdown의 3단계 제목을 의미합니다.
즉, 이 원칙은 Core Principles 아래에 포함되는 하위 항목입니다.
5. 첫 번째 원칙 예시 주석
<!-- Example: I. Library-First -->이 줄은 첫 번째 원칙 이름의 예시를 보여줍니다.
Library-First는 기능을 만들 때 먼저 독립적인 라이브러리 형태로 설계하자는 원칙입니다.
예를 들어 어떤 기능을 페이지 내부에 바로 작성하는 것이 아니라, 재사용 가능한 모듈이나 라이브러리 단위로 먼저 분리하는 개발 방식을 의미합니다.
블로그에서는 이렇게 설명할 수 있습니다.
이 주석은 첫 번째 원칙의 예시로 Library-First를 제시한다. 이는 기능을 특정 화면이나 파일에 종속시키기보다 독립적으로 테스트하고 재사용할 수 있는 라이브러리 단위로 설계하자는 의미이다.
6. 첫 번째 원칙 설명 자리
[PRINCIPLE_1_DESCRIPTION]이 줄은 첫 번째 원칙에 대한 실제 설명이 들어갈 자리입니다.
예를 들어 Library-First 원칙을 사용한다면 다음과 같이 작성할 수 있습니다.
Every feature starts as a standalone library where practical. Libraries must be self-contained, independently testable, and documented.한국어로 작성하면 다음과 같습니다.
모든 주요 기능은 가능한 한 독립적인 라이브러리 또는 모듈로 시작해야 한다. 각 모듈은 독립적으로 테스트 가능해야 하며, 목적과 사용법이 문서화되어야 한다.즉, 이 줄은 나중에 실제 프로젝트 원칙 설명으로 교체되어야 합니다.
7. 첫 번째 원칙 설명 예시
<!-- Example: Every feature starts as a standalone library; Libraries must be self-contained, independently testable, documented; Clear purpose required - no organizational-only libraries -->이 주석은 [PRINCIPLE_1_DESCRIPTION]에 어떤 내용을 넣으면 되는지 구체적인 예시를 제공합니다.
핵심 내용은 세 가지입니다.
첫째, 모든 기능은 독립적인 라이브러리로 시작해야 한다는 것입니다.
둘째, 라이브러리는 자체적으로 완결되어야 하고, 독립적으로 테스트 가능해야 하며, 문서화되어야 합니다.
셋째, 단순히 폴더 정리를 위해 의미 없는 라이브러리를 만들면 안 된다는 뜻입니다.
여기서 중요한 표현은 no organizational-only libraries입니다.
이는 “구조상 보기 좋아 보이기 위해서만 만든 불필요한 라이브러리는 허용하지 않는다”는 의미입니다.
Principle 2
8. 두 번째 원칙 제목
### [PRINCIPLE_2_NAME]
두 번째 핵심 원칙의 제목 자리입니다.
예시로는 다음과 같은 원칙을 넣을 수 있습니다.
### II. CLI Interface
또는 한국어 병기 방식으로 다음처럼 작성할 수 있습니다.
### II. 명령줄 인터페이스 제공 / CLI Interface9. 두 번째 원칙 예시 주석
<!-- Example: II. CLI Interface -->이 주석은 두 번째 원칙의 예시로 CLI Interface를 제시합니다.
CLI는 Command Line Interface의 약자입니다.
즉, 터미널에서 명령어로 실행할 수 있는 인터페이스를 의미합니다.
예를 들어 다음과 같은 명령어 형태를 생각할 수 있습니다.
npm run test
npm run lint
python main.py --input data.json이 원칙은 기능을 단순히 내부 코드로만 만들지 말고, 외부에서 실행하고 검증할 수 있는 명령어 형태를 제공하자는 의미입니다.
10. 두 번째 원칙 설명 자리
[PRINCIPLE_2_DESCRIPTION]두 번째 원칙에 대한 실제 설명이 들어갈 자리입니다.
예를 들어 CLI Interface 원칙이라면 다음과 같이 작성할 수 있습니다.
Every library exposes functionality via CLI. Inputs are accepted through stdin or arguments, outputs are written to stdout, and errors are written to stderr.한국어로는 다음과 같이 설명할 수 있습니다.
모든 주요 기능은 CLI를 통해 실행 가능해야 한다. 입력은 인자 또는 표준 입력으로 받고, 정상 출력은 stdout으로, 오류는 stderr로 출력해야 한다.11. 두 번째 원칙 설명 예시
<!-- Example: Every library exposes functionality via CLI; Text in/out protocol: stdin/args → stdout, errors → stderr; Support JSON + human-readable formats -->이 주석은 CLI 원칙을 어떻게 작성할 수 있는지 보여줍니다.
핵심은 다음과 같습니다.
- 입력은 stdin 또는 명령어 인자로 받습니다.
- 정상 결과는 stdout으로 출력합니다.
- 오류 메시지는 stderr로 출력합니다.
- 출력 형식은 JSON과 사람이 읽기 쉬운 형식을 모두 지원할 수 있습니다.
- 여기서 stdin, stdout, stderr는 운영체제의 표준 입출력 개념입니다.
| 용어 | 의미 |
| stdin | 표준 입력 |
| stdout | 표준 출력 |
| stderr | 표준 오류 출력 |
이런 규칙을 정하면 자동화 스크립트, CI/CD, 테스트 환경에서 기능을 쉽게 호출하고 검증할 수 있습니다.
Principle 3
12. 세 번째 원칙 제목
### [PRINCIPLE_3_NAME]세 번째 핵심 원칙의 제목 자리입니다.
예시로는 테스트 우선 개발 원칙이 들어갈 수 있습니다.
### III. Test-First (NON-NEGOTIABLE)한국어 병기 방식으로 작성하면 다음과 같습니다.
### III. 테스트 우선 / Test-First (NON-NEGOTIABLE)NON-NEGOTIABLE은 “협상 불가”라는 뜻입니다.
즉, 이 원칙은 선택 사항이 아니라 반드시 지켜야 하는 규칙이라는 의미입니다.
13. 세 번째 원칙 예시 주석
<!-- Example: III. Test-First (NON-NEGOTIABLE) -->이 주석은 세 번째 원칙의 예시로 Test-First를 제시합니다.
Test-First는 구현 코드를 먼저 작성하는 것이 아니라, 테스트 코드를 먼저 작성하는 개발 방식을 의미합니다.
일반적인 흐름은 다음과 같습니다.
테스트 작성 → 테스트 실패 확인 → 구현 코드 작성 → 테스트 통과 → 리팩터링이 방식은 TDD, 즉 Test-Driven Development와 연결됩니다.
14. 세 번째 원칙 설명 자리
[PRINCIPLE_3_DESCRIPTION]세 번째 원칙에 대한 실제 설명이 들어갈 자리입니다.
예를 들어 다음과 같이 작성할 수 있습니다.
Tests must be written before implementation code. The implementation begins only after the expected behavior is captured in failing tests.한국어로 작성하면 다음과 같습니다.
테스트 코드는 구현 코드보다 먼저 작성되어야 한다. 구현은 기대 동작이 실패하는 테스트로 명확히 표현된 이후에만 시작할 수 있다.이 문장은 프로젝트의 테스트 문화를 강하게 정의합니다.
15. 세 번째 원칙 설명 예시
<!-- Example: TDD mandatory: Tests written → User approved → Tests fail → Then implement; Red-Green-Refactor cycle strictly enforced -->이 주석은 테스트 우선 원칙을 더 구체적으로 설명합니다.
핵심 흐름은 다음과 같습니다.
Tests written → User approved → Tests fail → Then implement이를 풀어 쓰면 다음과 같습니다.
- 먼저 테스트를 작성합니다.
- 사용자가 테스트 의도를 승인합니다.
- 아직 구현이 없으므로 테스트가 실패해야 합니다.
- 그다음 구현 코드를 작성합니다.
또한 Red-Green-Refactor 사이클을 엄격히 따른다고 되어 있습니다.
| 단계 | 의미 |
| Red | 실패하는 테스트를 먼저 작성 |
| Green | 테스트를 통과할 만큼만 구현 |
| Refactor | 동작을 유지하면서 코드 구조 개선 |
즉, 이 원칙은 “코드부터 만들고 나중에 테스트하는 방식”을 금지하고, 테스트가 개발 방향을 이끌도록 강제합니다.
Principle 4
16. 네 번째 원칙 제목
### [PRINCIPLE_4_NAME]네 번째 핵심 원칙의 제목 자리입니다.
예시로는 다음과 같은 원칙이 들어갈 수 있습니다.
### IV. Integration Testing한국어 병기 방식으로는 다음과 같이 작성할 수 있습니다.
### IV. 통합 테스트 / Integration Testing17. 네 번째 원칙 예시 주석
<!-- Example: IV. Integration Testing -->이 주석은 네 번째 원칙의 예시로 Integration Testing을 제시합니다.
통합 테스트는 개별 함수나 모듈만 확인하는 것이 아니라, 여러 구성 요소가 함께 동작할 때 문제가 없는지 검증하는 테스트입니다.
예를 들어 Next.js 프로젝트라면 다음과 같은 부분이 통합 테스트 대상이 될 수 있습니다.
- API Route와 데이터베이스 연동
- 로그인 기능과 세션 처리
- 폼 입력 후 서버 액션 실행
- 프론트엔드 화면과 백엔드 응답의 연결
- 공통 스키마 변경 후 관련 기능 정상 동작 여부
18. 네 번째 원칙 설명 자리
[PRINCIPLE_4_DESCRIPTION]네 번째 원칙에 대한 실제 설명이 들어갈 자리입니다.
예를 들어 다음과 같이 작성할 수 있습니다.
Integration tests are required for new library contracts, contract changes, inter-service communication, and shared schemas.한국어로 작성하면 다음과 같습니다.
새로운 모듈 계약, 기존 계약 변경, 서비스 간 통신, 공유 스키마 변경이 발생하는 경우 통합 테스트를 반드시 작성해야 한다.여기서 contract는 함수, API, 모듈이 외부와 약속하는 입력과 출력의 규칙을 의미합니다.
19. 네 번째 원칙 설명 예시
<!-- Example: Focus areas requiring integration tests: New library contract tests, Contract changes, Inter-service communication, Shared schemas -->이 주석은 어떤 경우에 통합 테스트가 필요한지 예시를 제공합니다.
특히 다음 상황을 강조합니다.
| 항목 | 설명 |
| New library contract tests | 새 라이브러리나 모듈의 입력/출력 규칙 검증 |
| Contract changes | 기존 API나 함수 시그니처 변경 검증 |
| Inter-service communication | 서비스 간 통신 검증 |
| Shared schemas | 여러 영역에서 공유하는 데이터 구조 검증 |
이 주석의 핵심은 “변경 영향 범위가 넓은 부분은 반드시 통합 테스트로 검증해야 한다”는 것입니다.
Principle 5
20. 다섯 번째 원칙 제목
### [PRINCIPLE_5_NAME]다섯 번째 핵심 원칙의 제목 자리입니다.
여기에는 프로젝트 성격에 따라 다양한 원칙이 들어갈 수 있습니다.
예를 들어 다음 중 하나를 선택할 수 있습니다.
### V. Observability### V. Versioning & Breaking Changes### V. Simplicity한국어 병기 방식으로는 다음과 같이 작성할 수 있습니다.
### V. 관찰 가능성 / Observability또는
### V. 단순성 / Simplicity21. 다섯 번째 원칙 예시 주석
<!-- Example: V. Observability, VI. Versioning & Breaking Changes, VII. Simplicity -->이 주석은 다섯 번째 원칙 후보를 여러 개 제시합니다.
흥미로운 점은 V, VI, VII처럼 여러 번호가 등장한다는 것입니다.
이는 반드시 원칙이 5개로 제한되는 것은 아니라는 의미로 볼 수 있습니다.
즉, 프로젝트에 따라 핵심 원칙을 더 추가할 수 있습니다.
예를 들어 다음과 같이 확장할 수 있습니다.
### V. Observability
### VI. Versioning & Breaking Changes
### VII. Simplicity각 원칙의 의미는 다음과 같습니다.
| 원칙 | 의미 |
| Observability | 로그, 에러 추적, 디버깅 가능성 확보 |
| Versioning & Breaking Changes | 버전 관리와 호환성 깨짐 관리 |
| Simplicity | 불필요한 복잡성 제거 |
22. 다섯 번째 원칙 설명 자리
[PRINCIPLE_5_DESCRIPTION]다섯 번째 원칙에 대한 실제 설명이 들어갈 자리입니다.
예를 들어 Simplicity 원칙이라면 다음과 같이 작성할 수 있습니다.
Prefer the simplest solution that satisfies current requirements. Avoid speculative abstractions and unnecessary dependencies.한국어로는 다음과 같습니다.
현재 요구사항을 충족하는 가장 단순한 해결책을 우선한다. 미래를 과도하게 예측한 추상화나 불필요한 의존성 추가를 피한다.23. 다섯 번째 원칙 설명 예시
<!-- Example: Text I/O ensures debuggability; Structured logging required; Or: MAJOR.MINOR.BUILD format; Or: Start simple, YAGNI principles -->이 주석은 다섯 번째 원칙의 설명 예시를 여러 방향으로 제시합니다.
첫 번째 예시는 디버깅 가능성입니다.
Text I/O ensures debuggability텍스트 기반 입출력을 사용하면 로그 확인, 테스트, 자동화, 디버깅이 쉬워진다는 의미입니다.
두 번째 예시는 구조화된 로깅입니다.
Structured logging required단순 문자열 로그가 아니라 JSON처럼 구조화된 로그를 사용하라는 뜻입니다.
세 번째 예시는 버전 형식입니다.
MAJOR.MINOR.BUILD format버전을 다음과 같은 형식으로 관리하라는 뜻입니다.
1.0.0
2.1.3
3.0.0네 번째 예시는 단순성 원칙입니다.
Start simple, YAGNI principlesYAGNI는 You Aren’t Gonna Need It의 약자입니다.
즉, “아직 필요하지 않은 기능을 미리 만들지 말라”는 개발 원칙입니다.
Section 2
24. 두 번째 큰 섹션 제목
## [SECTION_2_NAME]이 줄은 두 번째 주요 섹션의 제목 자리입니다.
예시로는 다음과 같은 제목이 들어갈 수 있습니다.
## Additional Constraints## Security Requirements## Performance Standards한국어 병기 방식으로는 다음처럼 작성할 수 있습니다.
## 추가 제약사항 / Additional Constraints또는
## 보안 요구사항 / Security Requirements이 섹션은 핵심 원칙 외에 프로젝트에서 반드시 지켜야 하는 구체적인 제약 조건을 작성하는 영역입니다.
25. 두 번째 섹션 예시 주석
<!-- Example: Additional Constraints, Security Requirements, Performance Standards, etc. -->이 주석은 [SECTION_2_NAME]에 들어갈 수 있는 제목 예시를 제공합니다.
이 섹션에는 다음과 같은 내용을 넣을 수 있습니다.
- 기술 스택 제한
- 보안 규칙
- 성능 기준
- 접근성 기준
- 배포 정책
- 데이터 처리 기준
- 비밀정보 관리 규칙
예를 들어 Next.js 프로젝트라면 다음과 같은 내용을 작성할 수 있습니다.
## 보안과 비밀정보 처리 원칙 / Security & Secrets Management
API 키, 토큰, 비밀번호는 코드 저장소에 커밋할 수 없다. 모든 비밀정보는 환경 변수 또는 안전한 비밀 관리 도구를 통해 관리해야 한다.26. 두 번째 섹션 내용 자리
[SECTION_2_CONTENT]두 번째 섹션의 실제 내용이 들어갈 자리입니다.
예를 들어 Security Requirements 섹션이라면 다음과 같은 내용이 들어갈 수 있습니다.
Secrets must never be committed to the repository. Environment variables must be used for API keys, database URLs, and authentication tokens.한국어로는 다음처럼 쓸 수 있습니다.
API 키, 데이터베이스 URL, 인증 토큰과 같은 비밀정보는 저장소에 커밋할 수 없다. 모든 비밀정보는 환경 변수 또는 별도 보안 저장소를 통해 관리해야 한다.27. 두 번째 섹션 내용 예시
<!-- Example: Technology stack requirements, compliance standards, deployment policies, etc. -->이 주석은 두 번째 섹션에 들어갈 수 있는 내용의 예시를 보여줍니다.
| 항목 | 설명 |
| Technology stack requirements | 사용할 프레임워크, 언어, 라이브러리 기준 |
| Compliance standards | 법적·조직적 준수 기준 |
| Deployment policies | 배포 방식, 승인 절차, 배포 제한 사항 |
즉, 이 섹션은 “프로젝트 운영상 반드시 지켜야 하는 조건”을 정의하는 부분입니다.
Section 3
28. 세 번째 큰 섹션 제목
## [SECTION_3_NAME]세 번째 주요 섹션의 제목 자리입니다.
예시로는 다음과 같은 제목을 사용할 수 있습니다.
## Development Workflow## Review Process## Quality Gates한국어 병기 방식으로는 다음처럼 쓸 수 있습니다.
## 개발 워크플로우 / Development Workflow또는
## 리뷰 프로세스 / Review Process이 섹션은 실제 개발 절차와 검증 흐름을 정의하는 영역입니다.
29. 세 번째 섹션 예시 주석
<!-- Example: Development Workflow, Review Process, Quality Gates, etc. -->이 주석은 세 번째 섹션 제목의 예시를 제공합니다.
이 섹션은 주로 다음과 같은 내용을 다룹니다.
- 브랜치 생성 규칙
- Pull Request 작성 규칙
- 코드 리뷰 기준
- 테스트 통과 조건
- 린트 검사 조건
- 문서 업데이트 조건
- 배포 전 승인 절차
Quality Gates는 품질 관문이라는 뜻입니다.
즉, 코드가 병합되거나 배포되기 전에 반드시 통과해야 하는 기준입니다.
예를 들어 다음과 같은 규칙이 Quality Gate가 될 수 있습니다.
모든 테스트 통과
타입 검사 통과
린트 오류 없음
보안 경고 없음
문서 업데이트 완료30. 세 번째 섹션 내용 자리
[SECTION_3_CONTENT]세 번째 섹션의 실제 내용이 들어갈 자리입니다.
예를 들어 리뷰 프로세스를 정의한다면 다음과 같이 작성할 수 있습니다.
All pull requests must include a summary of changes, related issue references, test evidence, and documentation updates when applicable.한국어로는 다음과 같이 작성할 수 있습니다.
모든 Pull Request는 변경 요약, 관련 이슈, 테스트 결과, 필요한 문서 수정 내용을 포함해야 한다.31. 세 번째 섹션 내용 예시
<!-- Example: Code review requirements, testing gates, deployment approval process, etc. -->이 주석은 세 번째 섹션에 들어갈 수 있는 구체적인 항목을 제시합니다.
| 항목 | 설명 |
| Code review requirements | 코드 리뷰 필수 조건 |
| Testing gates | 테스트 통과 기준 |
| Deployment approval process | 배포 승인 절차 |
이 부분은 개발팀이 실제로 어떤 절차를 거쳐 코드를 병합하고 배포할 것인지를 정하는 곳입니다.
Governance 섹션
32. 거버넌스 섹션 제목
## Governance이 줄은 Governance, 즉 거버넌스 섹션을 시작합니다.
여기서 거버넌스는 constitution 문서를 어떻게 관리하고, 변경하고, 적용할 것인지를 정하는 규칙입니다.
쉽게 말하면 다음 질문에 답하는 영역입니다.
- 이 문서가 다른 규칙보다 우선하는가?
- 원칙을 바꾸려면 어떤 절차가 필요한가?
- Pull Request에서 constitution 준수를 어떻게 확인하는가?
- 예외가 필요한 경우 어떻게 기록하는가?
- 버전은 어떻게 관리하는가?
33. 거버넌스 예시 주석
<!-- Example: Constitution supersedes all other practices; Amendments require documentation, approval, migration plan -->이 주석은 거버넌스 규칙의 예시를 보여줍니다.
핵심은 세 가지입니다.
첫째, constitution은 다른 개발 관행보다 우선합니다.
Constitution supersedes all other practices즉, 팀에서 관습적으로 해오던 방식이 있더라도 constitution과 충돌하면 constitution이 우선한다는 뜻입니다.
둘째, constitution을 수정하려면 문서화가 필요합니다.
Amendments require documentation셋째, 수정에는 승인과 마이그레이션 계획이 필요합니다.
approval, migration plan예를 들어 테스트 원칙을 바꾸려면 단순히 문장만 수정하는 것이 아니라, 왜 바꾸는지, 기존 코드에는 어떤 영향이 있는지, 어떻게 전환할 것인지까지 기록해야 한다는 의미입니다.
34. 거버넌스 규칙 자리
[GOVERNANCE_RULES]실제 거버넌스 규칙이 들어갈 자리입니다.
예를 들어 다음과 같이 작성할 수 있습니다.
This constitution supersedes informal conventions and ad-hoc practices. All pull requests must verify compliance with the constitution. Amendments require documented rationale, review approval, and a migration plan.한국어로는 다음과 같이 작성할 수 있습니다.
이 constitution은 비공식 관행과 임시 규칙보다 우선한다. 모든 Pull Request는 constitution 준수 여부를 확인해야 한다. 원칙 수정은 변경 사유, 리뷰 승인, 마이그레이션 계획을 포함해야 한다.이 섹션은 constitution 자체의 권위를 부여하는 부분입니다.
35. 거버넌스 규칙 예시 주석
<!-- Example: All PRs/reviews must verify compliance; Complexity must be justified; Use [GUIDANCE_FILE] for runtime development guidance -->이 주석은 거버넌스 규칙에 포함할 수 있는 내용을 추가로 보여줍니다.
핵심 내용은 다음과 같습니다.
| 항목 | 의미 |
| All PRs/reviews must verify compliance | 모든 PR과 리뷰에서 constitution 준수 여부를 확인 |
| Complexity must be justified | 복잡한 설계는 반드시 이유를 설명해야 함 |
| Use [GUIDANCE_FILE] | 실제 개발 중 참고할 별도 가이드 파일을 사용 |
여기서 [GUIDANCE_FILE] 역시 자리표시자입니다.
예를 들어 다음과 같이 바꿀 수 있습니다.
Use copilot-instructions.md for runtime development guidance.또는
Use .github/copilot-instructions.md for implementation guidance.즉, constitution은 상위 원칙을 담고, 실제 구현 중 세부 지침은 별도의 가이드 문서에서 참고하도록 연결할 수 있습니다.
Version 정보
36. 버전, 제정일, 최종 수정일
**Version**: [CONSTITUTION_VERSION] | **Ratified**: [RATIFICATION_DATE] | **Last Amended**: [LAST_AMENDED_DATE]이 줄은 constitution 문서의 버전 정보를 나타냅니다.
각 항목의 의미는 다음과 같습니다.
| 항목 | 의미 |
| Version | constitution 문서의 버전 |
| Ratified | 처음 공식 승인된 날짜 |
| Last Amended | 마지막으로 수정된 날짜 |
예를 들어 다음과 같이 작성할 수 있습니다.
**Version**: 1.0.0 | **Ratified**: 2026-05-13 | **Last Amended**: 2026-05-13여기서 **텍스트**는 Markdown에서 굵은 글씨를 의미합니다.
즉, 실제 화면에서는 다음처럼 보입니다.
Version: 1.0.0 | Ratified: 2026-05-13 | Last Amended: 2026-05-13
37. 버전 정보 예시 주석
<!-- Example: Version: 2.1.1 | Ratified: 2025-06-13 | Last Amended: 2025-07-16 -->이 주석은 버전 정보를 어떻게 작성하면 되는지 예시를 보여줍니다.
예시에서는 다음 정보를 담고 있습니다.
| 항목 | 값 |
| Version | 2.1.1 |
| Ratified | 2025-06-13 |
| Last Amended | 2025-07-16 |
이런 형식은 constitution 문서가 언제 만들어졌고, 언제 변경되었는지 추적하기 위해 필요합니다.
특히 여러 사람이 협업하는 프로젝트에서는 원칙 문서가 변경될 때마다 버전을 올리고 수정 이력을 남기는 것이 중요합니다.
전체 구조 요약
이 constitution.md 템플릿은 크게 네 부분으로 구성됩니다.
| 섹션 | 역할 |
| 문서 제목 | 어떤 프로젝트의 constitution인지 표시 |
| Core Principles | 프로젝트의 핵심 개발 원칙 정의 |
| Section 2 | 보안, 성능, 기술 제약 등 추가 기준 정의 |
| Section 3 | 개발 워크플로우, 리뷰, 품질 관문 정의 |
| Governance | constitution의 적용 우선순위와 변경 절차 정의 |
| Version 정보 | 문서 버전, 제정일, 최종 수정일 기록 |
이 파일의 핵심 의도
이 파일은 단순한 README가 아닙니다.
README는 보통 프로젝트 소개, 설치 방법, 실행 방법을 설명합니다.
반면 constitution.md는 프로젝트가 어떤 기준으로 개발되어야 하는지 정의합니다.
즉, README가 “이 프로젝트를 어떻게 사용하는가”를 설명한다면, constitution.md는 “이 프로젝트를 어떤 원칙으로 만들어야 하는가”를 설명합니다.
자리표시자 정리
파일 안에 있는 대괄호 형태의 값들은 모두 실제 내용으로 교체해야 합니다.
| 자리표시자 | 교체할 내용 |
| [PROJECT_NAME] | 프로젝트 이름 |
| [PRINCIPLE_1_NAME] | 첫 번째 핵심 원칙 이름 |
| [PRINCIPLE_1_DESCRIPTION] | 첫 번째 핵심 원칙 설명 |
| [PRINCIPLE_2_NAME] | 두 번째 핵심 원칙 이름 |
| [PRINCIPLE_2_DESCRIPTION] | 두 번째 핵심 원칙 설명 |
| [PRINCIPLE_3_NAME] | 세 번째 핵심 원칙 이름 |
| [PRINCIPLE_3_DESCRIPTION] | 세 번째 핵심 원칙 설명 |
| [PRINCIPLE_4_NAME] | 네 번째 핵심 원칙 이름 |
| [PRINCIPLE_4_DESCRIPTION] | 네 번째 핵심 원칙 설명 |
| [PRINCIPLE_5_NAME] | 다섯 번째 핵심 원칙 이름 |
| [PRINCIPLE_5_DESCRIPTION] | 다섯 번째 핵심 원칙 설명 |
| [SECTION_2_NAME] | 두 번째 주요 섹션 제목 |
| [SECTION_2_CONTENT] | 두 번째 주요 섹션 내용 |
| [SECTION_3_NAME] | 세 번째 주요 섹션 제목 |
| [SECTION_3_CONTENT] | 세 번째 주요 섹션 내용 |
| [GOVERNANCE_RULES] | constitution 적용 및 변경 규칙 |
| [CONSTITUTION_VERSION] | 문서 버전 |
| [RATIFICATION_DATE] | 최초 승인일 |
| [LAST_AMENDED_DATE] | 최종 수정일 |
요약 정리
다음과 같이 정리할 수 있습니다.
.specify/memory/constitution.md는 프로젝트의 최상위 개발 원칙을 정의하는 문서이다. 이 파일은 기능 구현 방식, 테스트 우선 원칙, 통합 테스트 기준, 보안·성능 제약, 리뷰 절차, 거버넌스 규칙을 명문화하기 위한 템플릿이다.
특히 [PRINCIPLE_*], [SECTION_*] 형태의 값들은 실제 프로젝트 상황에 맞게 교체해야 하는 자리표시자이다. 따라서 이 파일은 완성된 규칙 문서라기보다는, 프로젝트 팀이 자신들의 개발 철학과 품질 기준을 체계적으로 작성하도록 돕는 constitution 초안이라고 볼 수 있다.
핵심 정리
이 파일은 다음 목적을 가집니다.
- 프로젝트의 개발 원칙을 명문화한다.
- 테스트, 리뷰, 품질 기준을 사전에 정의한다.
- 보안, 성능, 배포 같은 추가 제약을 문서화한다.
- PR과 코드 리뷰에서 따라야 할 기준을 제공한다.
- constitution 자체를 어떻게 변경할 수 있는지 거버넌스 규칙을 둔다.
- 문서 버전을 관리하여 원칙 변경 이력을 추적한다.
결론적으로 이 .specify/memory/constitution.md는 프로젝트의 기술적·조직적 의사결정 기준을 담는 최상위 규칙 문서의 템플릿입니다.
'AI Native > Github Spec Kit으로 구현하는 SDD v1' 카테고리의 다른 글
| copilot-instructions.md (0) | 2026.05.13 |
|---|---|
| Lab 03: 신규 기능을 위한 완전한 Spec Driven Development 사이클 (0) | 2026.05.13 |
| Lab 02: GitHub Spec Kit을 활용한 Spec Driven Development (0) | 2026.05.13 |
| Lab 01: Next.js 프로젝트에 테스트 환경 설정하기 (0) | 2026.05.13 |
| Lab 00: 로컬 Git 리포(todolist-app) → GitHub 원격(SSH) → feature 개발 → PR → merge → 로컬 동기화 (0) | 2026.05.13 |