Imported from ohama/software-design-in-the-age-of-ai (
experiment/runs/T-3-C_rS3/AGENTS.md). Install upstream withnpx skills add ohama/software-design-in-the-age-of-ai --skill T-3-C_rS3. Copyright stays with the author.
AGENTS.md
이 저장소에서 AI Agent 가 따라야 하는 작업 규칙이다. 코딩 가이드라인이 아니라 행동 정책이다.
1. Project Overview
Kotlin 으로 작성한 E-Commerce 예제. Domain-Driven Design 을 따른다.
Bounded Context: Sales · Payment · Inventory · Shipment
2. Source of Truth
| 알아야 할 것 | 문서 |
|---|---|
| 용어의 의미 | docs/glossary.md |
| 비즈니스 규칙과 생명주기 | docs/domain.md |
| 구조와 의존 규칙 | docs/architecture.md |
| Context 간 계약 | docs/contracts.md |
| 왜 그렇게 결정했는가 | docs/adr/ |
코드 주석과 문서가 충돌하면 문서를 따르고, 충돌 사실을 보고한다.
3. Before Making Changes
사소하지 않은 작업은 다음 순서를 따른다.
- 이 파일을 읽는다
docs/domain.md와docs/glossary.md를 읽는다docs/architecture.md의 Invariant 를 확인한다- 관련 ADR 을 확인한다
- 기존 구현과 테스트를 조사한다
- 계획을 세운 뒤 구현한다
계획 없이 바로 코드를 수정하지 않는다.
4. Build
./gradlew build5. Test
가장 좁은 범위부터 실행한다.
./gradlew test --tests "*OrderCancellation*"
./gradlew architectureTest
./gradlew test테스트 결과를 보고하지 않고 작업 완료를 선언하지 않는다.
6. Domain Rules
docs/domain.md 의 BR-001 ~ BR-006 을 따른다.
Business Rule 을 발명하지 않는다. 필요한 규칙이 없거나 모호하면 중단하고 보고한다.
docs/domain.md §7 의 Open Question(Q-001 · Q-002)은 아직 결정되지 않았다.
추측으로 구현하지 않는다.
7. Terminology
docs/glossary.md 의 용어를 사용한다.
- Forbidden Terms 를 도입하지 않는다 (Purchase · Transaction · Request 를 Order 의 동의어로 쓰지 않는다)
- Command 는 동사+목적어, Event 는 과거형, State 는 형용사로 명명한다
- 새 Domain 개념이 필요하면 먼저 제안하고 승인을 기다린다
8. Architecture Rules
docs/architecture.md §5 의 INV-001 ~ INV-008 을 위반하지 않는다.
특히:
Payment ✕→ Sales
Inventory ✕→ Sales
Domain ✕→ Infrastructure
contracts ✕→ 모든 ContextContext 간에는 ecommerce.contracts 의 Event 만 사용한다.
9. Change Scope
요청받은 범위 안에서만 변경한다.
하지 않는다:
- 관련 없는 리팩터링
- 광범위한 포맷 변경
- 불필요한 이름 변경
- 요구사항과 무관한 의존성 추가
범위를 넓혀야 한다면 중단하고 이유를 보고한다.
10. Tests
테스트는 실행 가능한 명세다. 비즈니스 행위를 이름에 담는다.
좋음 shouldRejectCancellationAfterShipmentStarted
나쁨 shouldCallCancelMethod테스트를 통과시키려고 테스트를 약화시키거나 삭제하지 않는다.
11. Documentation
다음이 바뀌면 문서도 함께 바꾼다.
| 변경 | 갱신할 문서 |
|---|---|
| Business Rule | docs/domain.md + 테스트 |
| 용어 | docs/glossary.md + 코드 + 테스트 |
| 의존 규칙 | docs/architecture.md + ArchitectureTest |
| Event 스키마 | docs/contracts.md + ADR |
12. Forbidden Actions
- Business Rule 을 발명한다
- 다른 Context 의 Domain Model 을 직접 참조한다
- 공개 Contract 를 조용히 변경한다
- 테스트를 지워서 빌드를 통과시킨다
- 실패한 테스트를 숨긴다
- 검증 없이 성공을 보고한다
13. Escalation
다음 상황에서는 중단하고 사람에게 확인한다.
- Domain Rule 이 모호하거나 충돌한다
- Architecture Invariant 를 바꿔야 한다
- Context 경계를 넘어야 한다
- 공개 Contract 를 바꿔야 한다
- 새 Domain 개념이 필요하다
- Open Question 에 대한 답이 필요하다
추측으로 해결하지 않는다.
14. Definition of Done
- 구현 완료
-
./gradlew test통과 -
./gradlew architectureTest통과 - 요청 범위를 벗어난 변경 없음
- Domain Rule 보존
- 필요한 문서 갱신
- 남은 위험 보고