사용 가이드

용도

이 저장소는 DDD 프로젝트의 설계 규칙을 정의한다. 다른 프로젝트는 이 저장소의 경로를 지정해 규칙 문서를 읽고, 그 기준으로 자기 설계에 문제가 없는지 검증한다.

규칙 문서는 src/content/docs 아래 Markdown으로 작성한다.
같은 문서가 이 사이트(사람용)와 검증 기준(Claude Code용)을 겸한다.

다른 프로젝트에서 사용하기

검증할 프로젝트에서 Claude Code를 실행하고, 그 프로젝트에 아래 두 가지를 설정한다.

1. 읽기 권한 등록

.claude/settings.json에 이 저장소 경로를 등록한다. 등록하면 규칙 문서를 읽을 때마다 권한을 묻지 않는다.

{
  "permissions": {
    "additionalDirectories": ["D:/dev/workspace/ddd_guide"]
  }
}

2. CLAUDE.md에 규칙 경로 명시

## DDD 설계 규칙

설계 규칙은 D:/dev/workspace/ddd_guide/src/content/docs 를 따른다.
도메인 모델·애그리거트·계층 구조를 설계하거나 검토할 때 먼저 이 문서를 읽고 규칙 위반 여부를 확인한다.

설정한 뒤에는 “DDD 규칙 기준으로 설계 검토해줘”처럼 요청하면 된다. 규칙 문서는 검증할 때마다 새로 읽으므로, 이 저장소에서 규칙을 고치면 다음 검증부터 바로 반영된다.

디렉토리·파일명 규칙

src/content/docs 아래의 디렉토리와 파일 이름은 다음 패턴을 따른다.

{접두사}_{토큰1}-{토큰2}.md   예: 01_usage-guide.md
{접두사}_{토큰1}-{토큰2}      예: 10_common, 20_aggregate-design

영단어로 짓는다.
접두사는 두 자리 숫자 일련번호로, 정렬 순서를 정한다. 한 자리 수는 앞에 0을 붙인다(예: 01, 02, 10).
접두사 다음에는 언더바(_)를 쓰고, 이름 안의 단어 구분에는 대시(-)를 쓴다.
소문자만 쓴다.

규칙 문서 작성 형식

규칙은 검증에 쓸 수 있도록, 설명이 아니라 판정 가능한 형태로 쓴다. 규칙마다 다음 항목을 갖춘다.

항목	내용
ID	영역 접두사와 번호(예: `AGG-01`). 한 번 부여한 ID는 바꾸거나 재사용하지 않는다.
규칙	한 줄 요약
이유	이 규칙이 필요한 이유
위반 판단 기준	무엇이 위반이고 무엇이 허용인지 구체적으로 적는다.
좋은 예 / 나쁜 예	코드나 모델 예시

ID를 고정하는 이유는 검증 결과가 “AGG-01 위반: Order.customer 필드”처럼 ID로 규칙을 가리키기 때문이다.

작성 예시

### AGG-01. 다른 애그리거트는 ID로만 참조한다

- **이유**: 객체로 참조하면 한 트랜잭션에서 여러 애그리거트를 함께 수정하게 되어 애그리거트 경계와 일관성 단위가 무너진다.
- **위반 판단 기준**: 애그리거트 내부의 필드가 다른 애그리거트 루트 타입이면 위반이다. 다른 애그리거트의 식별자 타입(`CustomerId` 등)이면 허용한다.

나쁜 예:

```java
class Order {
  private Customer customer;
}
```

좋은 예:

```java
class Order {
  private CustomerId customerId;
}
```

정적 분석 도구로 강제할 규칙

계층 간 의존 방향처럼 기계적으로 판정할 수 있는 규칙은 대상 프로젝트에서 정적 분석 도구로 강제하도록 표시하고, 설정 예시를 함께 적는다. Claude Code의 검토는 판단에 기반하므로 위반을 놓칠 수 있기 때문이다.

Java: ArchUnit
TypeScript: dependency-cruiser