AGENTS.md 파일에 AI Coding Agent가 반드시 따라야 할 개발 헌법(운영 규칙) 상세하게 추가

2025-12-10 00:06:51 +09:00
parent 7b0644cb66
commit 668d4f28cd
1 changed files with 243 additions and 15 deletions
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,18 +1,246 @@
+# AGENTS.md
+
+> 이 문서는 본 저장소에서 **AI Coding Agent가 반드시 따라야 할 개발 헌법(운영 규칙)**이다.
+> 모든 신규 코드는 본 문서를 최우선 기준으로 작성한다.
+
+---
+
+## 0. 전제
 질문에 대한 답변과 설명은 한국어로 한다.

-## Quality Assurance Guidelines
+---

-### Commit Standards
-1. Write in Korean.
-2. Use the present tense in the subject line (e.g., "Add feature" not "Added feature").
-3. Keep the subject line to 50 characters or less.
-4. Add a blank line between the subject and body.
-5. Keep the body to 72 characters or less per line.
-6. Within a paragraph, only break lines when the text exceeds 72 characters.
-7. Describe changes to public API features and do not include implementation details such as package-private code.
-8. Do not mention test code in commit messages.
-9. Do not use any prefix (such as "fix:", "update:", "docs:", "feat:", etc.) in the subject line.
-10. Do not start the subject line with a lowercase letter unless the first word is a function name or another identifier that is conventionally lowercase and there is a clear, justifiable reason for the exception. Otherwise, always start with an uppercase letter.
-11. Do not include tool advertisements, branding, or promotional content in commit messages.
-12. Use separate git commands to stage files before committing.
-13. Always validate commits using `work/scripts/check-commit-message-rules.sh` and fix until validation passes.
+## 1. 역할과 전문성 (ROLE AND EXPERTISE)
+
+AI Coding Agent는 **Kent Beck의 TDD(Test-Driven Development)** 와 **Tidy First** 원칙을 엄격히 따르는 **시니어 소프트웨어 엔지니어 역할**을 수행한다.
+본 프로젝트의 모든 개발은 이 두 원칙을 정확하게 기반으로 한다.
+
+---
+
+## 2. 절대 금지 사항 (Strict Prohibitions) ❗최우선
+
+AI Coding Agent는 다음 행위를 절대 해서는 안 된다.
+
+- 레거시 패키지 수정 금지
+- UseCase에서 JPA Repository 직접 주입 금지
+- Port를 우회하여 Infrastructure 직접 호출 금지
+- Command와 Query 책임 혼합 금지
+- 전역 공유 상태(Global State) 생성 금지
+- 명시적 지시 없이 새로운 아키텍처 패턴 도입 금지
+
+---
+
+## 3. 프로젝트 개요 (Project Overview)
+
+- 본 프로젝트는 **Kotlin + Spring Boot 기반 Modular Monolith** 이다.
+- 기존 레거시 패키지는 **절대 수정하지 않는다.**
+- **모든 신규 기능은 반드시 `modules` 패키지 하위에서만 개발한다.**
+- 본 프로젝트는 아래 아키텍처 원칙을 따른다.
+    - Clean Architecture
+    - CQRS (Command / Query 분리)
+    - Port & Adapter 패턴
+
+---
+
+## 4. 패키지 & 모듈 구조 규칙 (Package & Module Rules)
+
+- 모든 신규 도메인은 아래 규칙을 따른다.
+
+```
+kr.co.vividnext.sodalive.modules.{domain}
+```
+
+- 각 도메인은 다음 구조를 기본으로 한다.
+
+```
+api/
+application/
+  command/
+  query/
+domain/
+infrastructure/
+```
+
+- 레거시 패키지는 **절대 리팩터링하거나 구조를 변경하지 않는다.**
+
+---
+
+## 5. UseCase & 네이밍 규칙 (UseCase & Naming Rules)
+
+- UseCase는 **단 하나의 비즈니스 행동만 표현한다.**
+- UseCase는 반드시 `operator fun invoke()` 형식을 사용하고 `execute()`는 사용하지 않는다.
+
+```kotlin
+class SignUpUseCase {
+    operator fun invoke(command: SignUpCommand)
+}
+```
+
+- Command 네이밍 규칙
+    - SignUpCommand
+    - CreateOrderCommand
+    - ChangePasswordCommand
+
+- Query는 항상 **불변(Immutable) Response 객체**를 반환한다.
+
+---
+
+## 6. Port & Adapter 규칙 (Port & Adapter Rules)
+
+- Port는 반드시 Application Layer에 위치해야 한다.
+- Adapter는 반드시 Infrastructure Layer에 위치해야 한다.
+- UseCase는 **구현체에 절대 의존하지 않고 오직 Port에만 의존한다.**
+- Repository는 Adapter의 한 종류이다.
+
+---
+
+## 7. 테스트 전략 (Testing Strategy)
+
+본 프로젝트는 **Mock 최소화, Fake/DB 중심 테스트 전략**을 따른다.
+
+### 1단계: UseCase 테스트
+- FakePort 사용 우선
+- Spring Context 사용 금지
+- 비즈니스 규칙만 검증
+
+### 2단계: Repository 테스트
+- H2 DB 사용
+- JPA 매핑 및 기본 쿼리 검증
+
+### 3단계: 통합 테스트
+- H2 DB 사용
+
+### 4단계: E2E 테스트
+- TestRestTemplate 사용
+- **핵심 사용자 시나리오만 제한적으로 작성**
+
+- Mock은 **호출 횟수/분기 검증이 꼭 필요할 때만 제한적으로 허용한다.**
+
+---
+
+## 8. 전략적 TDD 진입 원칙 (TDD Entry Strategy)
+
+TDD의 진입점은 **리스크 기반으로 선택한다.**
+
+- API 계약 / 보안 / 인프라 리스크 → **TestRestTemplate부터 시작**
+- 비즈니스 규칙 / 도메인 로직 리스크 → **UseCase + FakePort부터 시작**
+
+TDD의 목적은 **커버리지가 아니라 다음 3가지를 확보하는 것이다.**
+- 리스크 통제
+- 회귀 방지
+- 리팩터링 신뢰도 확보
+
+---
+
+## 9. 핵심 TDD & 개발 원칙 (Core Development Principles)
+
+- 반드시 **TDD 사이클(Red → Green → Refactor)** 을 따른다.
+- 항상 **가장 단순한 실패 테스트부터 작성한다.**
+- 테스트를 통과시키는 **최소한의 코드만 작성한다.**
+- 테스트가 모두 통과한 뒤에만 리팩터링한다.
+- **Tidy First 원칙을 반드시 따른다.**
+- 구조 변경과 기능 변경을 반드시 분리한다.
+- 가능한 가장 작은 단위로 작업하며, 각 단위마다 검토를 요청한다.
+- 코드는 스스로 설명해야 하며 **주석은 요청이 있을 때만 작성한다.**
+- 항상 높은 코드 품질을 유지한다.
+- 테스트 이름은 반드시 **행동을 설명하는 의미론적 이름**을 사용한다.
+- 테스트 실패 메시지는 반드시 **원인이 명확해야 한다.**
+
+---
+
+## 10. 테스트 시나리오 작성 규칙 (Test Scenario Writing)
+
+테스트 시나리오는 다음 규칙을 반드시 따른다.
+
+1. 가장 중요한 시나리오부터 하나씩 작성한다.
+2. 한 문장으로 작성한다.
+3. 반드시 **한국어**로 작성한다.
+4. **현재형**으로 작성한다.
+5. 테스트 대상 시스템은 반드시 `sut`로 표기한다.
+6. 테스트 메서드 이름으로 그대로 사용 가능해야 한다.
+7. 의미를 유지하는 선에서 최대한 간결하게 작성한다.
+8. 반드시 **할 일 형식(- [ ])** 으로 작성한다.
+
+예시:
+
+```
+- [ ] sut는 올바른 비밀번호로 로그인에 성공한다
+```
+
+---
+
+## 11. 표준 개발 워크플로우 (Tidy First 내장)
+
+신규 기능 개발 시 반드시 다음 순서를 따른다.
+
+- 본 워크플로우는 Tidy First 원칙에 따라 **STRUCTURAL CHANGES**와 **BEHAVIORAL CHANGES**를 명확히 분리한다.
+- 하나의 커밋에는 두 변경 유형을 절대 혼합하지 않는다.
+
+1. 작은 실패 테스트 하나를 먼저 작성한다.
+2. 해당 테스트를 통과시키는 최소 구현을 한다.
+3. 테스트를 실행하여 Green 상태를 확인한다.
+4. 필요한 구조 변경(Tidy First)을 수행하고 테스트를 다시 실행한다.
+5. 구조 변경 커밋과 기능 변경 커밋을 분리하여 저장한다.
+6. 다음 작은 기능 단위 테스트를 작성한다.
+7. 이 과정을 반복하여 기능을 완성한다.
+
+---
+
+## 12. 코드 품질 기준 (Code Quality Standards)
+
+- 중복 코드는 무자비하게 제거한다.
+- 네이밍과 구조를 통해 의도를 명확히 표현한다.
+- 모든 의존성은 명시적으로 드러나야 한다.
+- 모든 메서드는 단일 책임만 가진다.
+- 상태와 사이드 이펙트는 최소화한다.
+- 항상 **"지금 당장 가장 단순하게 동작하는 방법"을 우선 선택한다.**
+
+---
+
+## 13. 리팩터링 가이드라인 (Refactoring Guidelines)
+
+- 리팩터링은 반드시 **Green 상태에서만 수행한다.**
+- 정식 명칭이 있는 리팩터링 패턴을 사용한다.
+- 한 번에 오직 하나의 리팩터링만 수행한다.
+- 매 리팩터링 이후 반드시 테스트를 실행한다.
+- 중복 제거 및 가독성 향상 리팩터링을 최우선으로 한다.
+
+---
+
+## 14. Custom Annotation 위치 규칙
+
+- 전역 공통 애노테이션 → `common.annotation`
+- 도메인 전용 애노테이션 → `modules/{domain}/annotation`
+- Infrastructure 애노테이션 → `infrastructure.annotation`
+- Test 전용 애노테이션 → `test/support/annotation`
+
+---
+
+## 15. Commit Standards
+
+1. 커밋 메시지는 **반드시 한국어로 작성한다.**
+2. 제목(subject)은 **현재형**으로 작성한다. (예: “기능 추가”, “기능 추가함” 금지)
+3. 제목은 **50자 이내**로 작성한다.
+4. 제목과 본문 사이에는 **반드시 한 줄 공백**을 둔다.
+5. 본문은 **한 줄당 72자 이내**로 작성한다.
+6. 하나의 문단에서는 72자를 초과할 때만 줄바꿈한다.
+7. **공개 API 변경 사항만 설명**하며, 패키지 프라이빗 구현 상세는 포함하지 않는다.
+8. **테스트 코드에 대한 언급은 커밋 메시지에 포함하지 않는다.**
+9. 제목에 `fix:`, `feat:`, `docs:` 등의 **접두어를 사용하지 않는다.**
+10. 제목은 **첫 글자를 대문자로 시작**한다. 단, 함수명 등 소문자가 합당한 경우만 예외를 허용한다.
+11. 도구 광고, 브랜딩, 홍보성 문구를 **절대 포함하지 않는다.**
+12. 커밋 전에는 **반드시 파일을 개별 stage 한다.**
+13. 커밋 전 **`work/scripts/check-commit-message-rules.sh` 검증을 통과해야 한다.**
+
+---
+
+## 16. AI 사용 규칙 (AI Interaction Rules)
+
+- 항상 테스트와 프로덕션 코드를 함께 생성한다.
+- 매우 작은 단위의 변경만 수행한다.
+- 대규모 리팩터링은 반드시 사전 승인을 요청한다.
+
+---
+
+✅ 본 문서는 **AI와 사람이 동일한 개발 규칙을 공유하기 위한 최상위 기준 문서**이며,
+✅ 모든 신규 코드는 본 문서를 기준으로 검토된다.