213 lines
6.4 KiB
Markdown
213 lines
6.4 KiB
Markdown
# 표준 적용 우선순위와 충돌 해결 규칙
|
|
|
|
## 목적
|
|
|
|
이 문서는 프로젝트 내 모든 standards/examples 문서를 **어떤 상황에서 어떤 순서로 읽고 적용할지** 정의한다.
|
|
|
|
이 문서의 목적은 다음과 같다.
|
|
|
|
- 작업마다 필요한 표준이 빠지지 않게 한다
|
|
- 여러 표준이 동시에 걸릴 때 우선순위를 명확히 한다
|
|
- AGENTS.md를 짧게 유지하면서도 실제 표준 적용 누락을 막는다
|
|
- AI가 “문서가 있었지만 읽지 않았다”는 상태를 줄인다
|
|
|
|
---
|
|
|
|
## 기본 원칙
|
|
|
|
- `AGENTS.md`는 **백과사전이 아니라 라우터**다
|
|
- 실제 규칙의 source of truth는 `docs/standards/**` 이다
|
|
- 실제 구현의 기준 예시는 `docs/examples/**` 이다
|
|
- architecture 문서는 레이어 책임과 의존 방향의 최상위 기준이다
|
|
- examples는 standards를 대체하지 않는다. 항상 **standards -> examples** 순서로 본다
|
|
|
|
---
|
|
|
|
## 우선순위
|
|
|
|
충돌 시 아래 순서대로 우선한다.
|
|
|
|
1. 직접적인 system / developer / user instruction
|
|
2. 더 깊게 중첩된 `AGENTS.md`
|
|
3. 더 바깥의 `AGENTS.md`
|
|
4. `/docs/architecture/README.md`
|
|
5. 이 문서에 의해 강제되는 relevant standards
|
|
6. relevant examples
|
|
7. 현재 코드베이스의 기존 패턴
|
|
8. 개인 선호 / 임시 편의
|
|
|
|
즉:
|
|
- “기존 코드가 이렇게 되어 있다”는 이유만으로 architecture나 standards를 깨면 안 된다
|
|
- examples가 standards와 충돌하면 standards를 우선한다
|
|
- 표준이 없을 때만 기존 코드 패턴을 참고한다
|
|
|
|
---
|
|
|
|
## 작업 시작 절차
|
|
|
|
모든 작업은 아래 순서로 진행한다.
|
|
|
|
1. 수정 대상 레이어를 식별한다
|
|
2. 경계 crossing 여부를 식별한다
|
|
- HTTP 경계
|
|
- transaction 경계
|
|
- DB query 경계
|
|
- external API 경계
|
|
- security/authentication 경계
|
|
3. root AGENTS와 nearest module AGENTS를 읽는다
|
|
4. 해당 작업에 필요한 standards를 읽는다
|
|
5. 필요한 경우 examples를 읽는다
|
|
6. 구현 전 “적용할 표준 목록”을 짧게 정리한다
|
|
7. 구현한다
|
|
8. 구현 후 standards 위반 여부를 다시 확인한다
|
|
|
|
---
|
|
|
|
## 표준 읽기 규칙
|
|
|
|
### 전역 기준: 항상 먼저 읽는다
|
|
|
|
아래 문서는 모든 작업 전에 기본적으로 적용된다.
|
|
|
|
- `/docs/standards/language/stream.md`
|
|
- `/docs/standards/language/optional.md`
|
|
- `/docs/standards/language/null.md`
|
|
- `/docs/standards/language/collections-immutability.md`
|
|
- `/docs/standards/language/enum-constants.md`
|
|
- `/docs/standards/language/time.md`
|
|
- `/docs/standards/language/exceptions.md`
|
|
- `/docs/standards/language/duplication.md`
|
|
- `/docs/standards/language/javadoc.md`
|
|
|
|
### 상황별 기준: 작업 유형에 따라 추가로 읽는다
|
|
|
|
#### controller / dto / api 응답 / validation / 인증 객체 접근 변경
|
|
추가로 읽는다:
|
|
- `/docs/standards/web/**`
|
|
- `/docs/standards/spring/filter-interceptor-resolver-advice.md`
|
|
|
|
#### use case / service / transaction / port 변경
|
|
추가로 읽는다:
|
|
- `/docs/standards/spring/transaction.md`
|
|
- `/docs/standards/spring/abstraction.md`
|
|
|
|
#### external API / client / serialization / timeout / retry 변경
|
|
추가로 읽는다:
|
|
- `/docs/standards/integration/**`
|
|
|
|
#### repository / entity / query / lock / migration 변경
|
|
추가로 읽는다:
|
|
- `/docs/standards/db/**`
|
|
|
|
#### configuration / bean wiring / security filter / bootstrap adapter 변경
|
|
추가로 읽는다:
|
|
- `/docs/standards/spring/**`
|
|
- `/docs/standards/integration/logging.md`
|
|
|
|
#### env / profile / docs / runbook / migration 절차 변경
|
|
추가로 읽는다:
|
|
- `/docs/standards/ops/**`
|
|
|
|
---
|
|
|
|
## examples 사용 규칙
|
|
|
|
examples는 아래 조건을 만족할 때만 사용한다.
|
|
|
|
- relevant standard를 먼저 읽었다
|
|
- example가 같은 레이어/비슷한 책임을 가진다
|
|
- architecture와 충돌하지 않는다
|
|
|
|
examples 사용 규칙:
|
|
- examples는 복붙 대상이 아니라 **형태와 책임 분리의 기준**이다
|
|
- example가 현재 standard와 충돌하면 example를 버린다
|
|
- example가 오래되었거나 애매하면 standard만 따르고 example는 무시한다
|
|
|
|
---
|
|
|
|
## 충돌 해결 규칙
|
|
|
|
### 1. example vs standard
|
|
- standard 우선
|
|
|
|
### 2. 기존 코드 패턴 vs standard
|
|
- standard 우선
|
|
- 단, 기존 코드가 널리 퍼져 있으면 한 번에 다 고치지 않고 현재 변경 범위에서만 맞춘다
|
|
|
|
### 3. 모듈 AGENTS vs root AGENTS
|
|
- 더 가까운 module AGENTS 우선
|
|
- 단, root의 전역 기준을 무시하는 근거로 쓰면 안 된다
|
|
|
|
### 4. 성능 최적화 vs 가독성
|
|
- 측정 근거 없는 성능 주장은 금지
|
|
- 기본값은 명확한 코드
|
|
- 성능 민감 경로는 측정 결과가 있으면 예외 허용
|
|
|
|
### 5. 빠른 구현 vs 구조 일관성
|
|
- 임시 구현으로 레이어를 깨는 것 금지
|
|
- 오늘 편한 구조보다 이후 반복 작업에서 덜 무너지는 구조를 우선
|
|
|
|
---
|
|
|
|
## AI 작업 지시 규칙
|
|
|
|
AI에게 작업을 줄 때는 다음을 포함한다.
|
|
|
|
- 수정 목표
|
|
- 파일 경로 또는 모듈 이름
|
|
- 변경 범위
|
|
- 관련 standards 파일
|
|
- 관련 examples 파일
|
|
- 금지사항
|
|
- 완료 조건
|
|
|
|
프롬프트는 이슈처럼 쓴다.
|
|
즉:
|
|
- 무엇을 바꿀지
|
|
- 어디를 바꿀지
|
|
- 어떤 기준을 따를지
|
|
- 무엇을 하지 말아야 하는지
|
|
를 명확히 적는다.
|
|
|
|
큰 변경은 바로 구현부터 시키지 말고:
|
|
1. Ask mode로 구현 계획
|
|
2. relevant standards/examples 확인
|
|
3. Code mode로 구현
|
|
순서로 진행한다.
|
|
|
|
---
|
|
|
|
## 표준 누락 방지 규칙
|
|
|
|
새 standards 파일을 만들면 반드시 아래를 함께 갱신한다.
|
|
|
|
- root AGENTS의 전역/폴더 라우팅 또는 relevant module AGENTS
|
|
- 관련 module AGENTS의 `Read first`
|
|
- 관련 examples 연결
|
|
- 이 문서의 상황별 기준 목록이 바뀌어야 하는지 검토
|
|
|
|
즉 파일만 만들고 라우팅하지 않는 것을 금지한다.
|
|
|
|
---
|
|
|
|
## 구현 전 체크리스트
|
|
|
|
- 이 작업의 owning layer는 어디인가?
|
|
- 어떤 boundary를 건드리는가?
|
|
- 전역 language standard를 읽었는가?
|
|
- 이 작업에 필요한 module-specific standard를 읽었는가?
|
|
- example는 relevant standard를 읽은 뒤에 봤는가?
|
|
- 충돌 시 무엇을 우선할지 명확한가?
|
|
|
|
---
|
|
|
|
## 구현 후 체크리스트
|
|
|
|
- architecture 위반이 없는가?
|
|
- 레이어 책임이 흐려지지 않았는가?
|
|
- 예외 번역 위치가 맞는가?
|
|
- transaction 범위가 맞는가?
|
|
- query/lock/migration 기준을 위반하지 않았는가?
|
|
- stale Javadoc/docs가 남지 않았는가?
|
|
- example를 그대로 복붙해 책임이 섞이지 않았는가?
|