Skip to content

Commit e2a1f5c

Browse files
lunarbae628lunarbae628
committed
Merge: Read Model 이벤트 재시도 처리 staging 변경사항 dev 반영
2 parents 306bcf9 + 99779ed commit e2a1f5c

14 files changed

Lines changed: 1507 additions & 40 deletions

File tree

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,17 @@
77
## 📚 Reference
88

99

10+
## 🤖 AI 보조 작업 기록
11+
- 사용하지 않았다면 이 섹션을 삭제해 주세요.
12+
- 사용 범위:
13+
- 채택한 제안과 이유:
14+
- 기각한 제안과 이유:
15+
- 실행한 검증:
16+
- 남은 리스크:
17+
18+
1019
## ✅ Check List
1120
- [ ] 코드가 정상적으로 컴파일되나요?
1221
- [ ] 테스트 코드를 통과했나요?
1322
- [ ] merge할 브랜치의 위치를 확인했나요?
14-
- [ ] Label을 지정했나요?
23+
- [ ] Label을 지정했나요?

‎.gitignore‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
HELP.md
2+
.DS_Store
23
.gradle
34
build/
45
!gradle/wrapper/gradle-wrapper.jar
@@ -51,3 +52,6 @@ infra/mysql/logs/
5152
# Perf benchmark outputs
5253
perf/**/results/*
5354
!perf/**/results/.gitkeep
55+
56+
# Local documentation and portfolio drafts
57+
docs/local/

‎AGENTS.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
# AGENTS.md
2+
3+
이 저장소에서 AI 보조 개발을 수행할 때 따르는 규칙입니다.
4+
5+
상세 작업 흐름: [`ai/ai-assisted-development-workflow.md`](ai/ai-assisted-development-workflow.md)
6+
7+
## 구현 전 계획
8+
9+
- 기능 추가, 리팩터링, 버그 수정 요청을 받더라도 바로 파일을 수정하지 않는다.
10+
- 먼저 기존 구조를 확인하고 다음 내용을 제시한다.
11+
- 해결하려는 문제
12+
- 변경이 필요한 파일
13+
- API, 데이터베이스, 호환성 영향
14+
- 필요한 테스트
15+
- 예상 리스크와 의도적으로 제외할 범위
16+
- 사용자가 즉시 구현을 명시적으로 요청하지 않았다면 승인 후 파일을 수정한다.
17+
18+
## 문서 작성 언어
19+
20+
- 저장소에 추가하는 문서, 설계안, 구현 계획, 리뷰 요약은 한국어로 작성한다.
21+
- 외부 도구나 라이브러리의 고유 용어는 필요한 경우 원문을 병기할 수 있다.
22+
23+
## 변경 범위 제한
24+
25+
- 승인된 계획에 필요한 파일만 수정한다.
26+
- 영향을 먼저 설명하지 않고 API 계약, 데이터베이스 스키마, 관련 없는 서식을 변경하지 않는다.
27+
- AI가 만들지 않은 변경을 되돌리거나 덮어쓰지 않는다.
28+
29+
## Git 작업 제한
30+
31+
- 사용자가 명시적으로 요청하지 않는 한 commit, push, merge, rebase를 수행하지 않는다.
32+
- 커밋이 필요해 보이면 먼저 변경 범위와 추천 커밋 메시지를 제안한다.
33+
- 사용자가 직접 커밋하거나 push하겠다고 말한 경우에는 명령을 실행하지 않고 필요한 확인 정보만 제공한다.
34+
35+
## 구현과 리뷰 분리
36+
37+
- 구현 단계에서는 승인된 계획을 따르고 계획에서 벗어난 변경을 보고한다.
38+
- 리뷰 단계에서는 명시적으로 요청받지 않는 한 코드를 수정하지 않는다. 버그, 회귀 가능성, 누락된 테스트, 근거가 부족한 주장을 찾는다.
39+
- AI가 생성한 코드는 테스트와 사람의 리뷰로 확인하기 전까지 신뢰하지 않는다.
40+
41+
## Review guidelines
42+
43+
Codex GitHub Code Review가 PR 리뷰에서 따라야 할 기준이다.
44+
45+
- 리뷰 코멘트는 한국어로 작성한다.
46+
- 각 코멘트는 심각도, 문제 상황, 위험, 수정 방향을 짧게 포함한다.
47+
- 트랜잭션 경계와 부분 실패 가능성을 확인한다.
48+
- 비동기 작업의 유실, 중복 처리, 재시도 경로를 확인한다.
49+
- API와 데이터베이스 호환성 회귀를 확인한다.
50+
- 누락된 테스트와 근거가 부족한 성능 주장을 확인한다.
51+
- AI 워크플로우 문서를 리뷰할 때는 과장된 성과 표현, 비밀 정보 노출 위험, 실제 구현 전 주장된 자동화 여부를 확인한다.
52+
- 사소한 서식보다 기능 오류와 운영 리스크를 우선한다.
53+
54+
## 판단 기록
55+
56+
- PR에 다음 내용을 정리한다.
57+
- AI를 사용한 범위
58+
- 채택하거나 기각한 제안
59+
- 수행한 검증
60+
- 남은 리스크
61+
- 비밀 정보, 인증 정보, 개인정보, 관련 없는 대화가 포함될 수 있는 원본 프롬프트와 도구 실행 로그를 커밋하지 않는다.

‎ai/README.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
# AI 보조 개발 문서
2+
3+
이 폴더는 Docsa에서 AI를 어떻게 통제하고 검증하는지 설명하는 문서를 모은다.
4+
5+
| 문서 | 역할 |
6+
| --- | --- |
7+
| [`ai-assisted-development-workflow.md`](ai-assisted-development-workflow.md) | 전체 작업 흐름과 단계별 산출물 |
8+
| [`logging-hook-reproducibility-plan.md`](logging-hook-reproducibility-plan.md) | Logging Hook과 검증 재현성 구축 계획 |
9+
10+
저장소 루트의 `AGENTS.md`는 AI가 따라야 할 실행 규칙이다. 이 폴더의 문서는 사람이 작업 방식과 판단 근거를 이해할 수 있도록 설명한다.

‎ai/ai-assisted-development-workflow.md‎

Lines changed: 287 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,287 @@
1+
# AI 보조 개발 워크플로우
2+
3+
## 1. 목적
4+
5+
AI가 코드를 빠르게 생성하는 것보다 변경 범위와 리스크를 사람이 이해하고 검증할 수 있도록 관리하는 것을 목표로 한다.
6+
7+
이 워크플로우는 다음 질문에 답할 수 있어야 한다.
8+
9+
- AI는 어떤 범위에서 사용됐는가
10+
- 구현 전에 어떤 영향과 리스크를 검토했는가
11+
- 어떤 제안을 사람이 채택하거나 기각했는가
12+
- 구현 결과는 별도 리뷰와 테스트를 거쳤는가
13+
- 다른 사람이 변경 이유와 검증 방법을 다시 확인할 수 있는가
14+
15+
## 2. 핵심 원칙
16+
17+
1. AI는 구현 전에 기존 구조와 영향 범위를 분석한다.
18+
2. 사람은 계획을 검토하고 승인한다.
19+
3. AI는 승인된 범위 안에서만 구현한다.
20+
4. 구현과 리뷰는 다른 작업으로 분리한다.
21+
5. 사람은 리뷰 의견의 채택 여부를 최종 판단한다.
22+
6. 테스트 결과와 남은 리스크를 PR에 기록한다.
23+
7. 원본 로그보다 설명 가능한 판단과 검증 결과를 우선한다.
24+
25+
## 3. 역할 구분
26+
27+
| 역할 | 책임 | 하지 않는 일 |
28+
| --- | --- | --- |
29+
| 사람 | 문제 정의, 계획 승인, 제안 채택과 기각, 최종 검증 | AI 결과를 검토 없이 수용하지 않는다 |
30+
| 구현 AI | 구조 분석, 계획 제안, 승인 범위 구현, 테스트 실행 | 승인 전 파일을 수정하지 않는다 |
31+
| 리뷰 AI | diff 기반 오류, 회귀, 누락 테스트, 운영 리스크 검토 | 리뷰 중 코드를 직접 수정하지 않는다 |
32+
| Logging Hook | 도구 실행과 검증 흐름 기록 | 코드 정확성이나 동일 결과 생성을 보장하지 않는다 |
33+
34+
구현 AI와 리뷰 AI는 같은 모델을 사용해도 된다. 다만 리뷰 AI는 구현 대화의 맥락보다 PR diff와 리뷰 기준을 중심으로 검토해야 한다.
35+
36+
## 4. 현재 적용 상태
37+
38+
| 항목 | 상태 | 근거 |
39+
| --- | --- | --- |
40+
| 전역 AI 작업 원칙 | 적용 중 | `~/.codex/AGENTS.md` |
41+
| 저장소별 작업 규칙 | 적용 중 | `AGENTS.md` |
42+
| AI 사용 판단 기록 | 적용 시작 | `.github/PULL_REQUEST_TEMPLATE.md` |
43+
| 구현과 GitHub PR 리뷰 분리 | 적용 시작 | Codex GitHub Code Review |
44+
| 도구 실행 Logging Hook | 계획 | [`logging-hook-reproducibility-plan.md`](logging-hook-reproducibility-plan.md) |
45+
| 검증 재현성 효과 측정 | 계획 | Hook과 PR 기록 누적 후 확인 |
46+
47+
## 5. 1회 설정
48+
49+
### 5.1 전역 규칙
50+
51+
전역 `~/.codex/AGENTS.md`에는 모든 프로젝트에 공통으로 적용할 개인 원칙을 둔다.
52+
53+
- 구현 전 가정과 트레이드오프 확인
54+
- 최소 범위 변경
55+
- 관련 없는 코드 수정 금지
56+
- 검증 가능한 성공 조건 정의
57+
58+
### 5.2 저장소 규칙
59+
60+
루트 `AGENTS.md`에는 Docsa에서 지킬 구체적인 규칙을 둔다.
61+
62+
- 구현 전 변경 파일과 영향 범위 제시
63+
- 승인 전 파일 수정 금지
64+
- API와 데이터베이스 호환성 검토
65+
- 구현과 리뷰 역할 분리
66+
- PR에 AI 사용 범위와 판단 기록
67+
68+
리뷰 기준은 Codex GitHub Code Review가 명확히 인식할 수 있도록 `## Review guidelines` 섹션에 둔다.
69+
70+
- 리뷰 코멘트는 한국어로 작성한다.
71+
- 사소한 서식보다 기능 오류, 데이터 정합성, 운영 리스크, 누락 테스트를 우선한다.
72+
- AI 워크플로우 문서는 실제 구현 전 주장된 자동화나 과장된 효과 표현을 확인한다.
73+
74+
### 5.3 PR 기록 구조
75+
76+
PR 템플릿에는 다음 내용을 기록한다.
77+
78+
```markdown
79+
## AI 보조 작업 기록
80+
81+
- 사용 범위:
82+
- 채택한 제안과 이유:
83+
- 기각한 제안과 이유:
84+
- 실행한 검증:
85+
- 남은 리스크:
86+
```
87+
88+
### 5.4 Codex GitHub Code Review
89+
90+
GitHub PR에서 구현과 리뷰를 분리하기 위해 Codex Code Review를 사용한다.
91+
92+
1. Codex Cloud에 GitHub 저장소를 연결한다.
93+
2. Codex Code Review 설정에서 저장소의 Code review를 활성화한다.
94+
3. 처음에는 Automatic reviews를 끄고 수동 리뷰로 동작을 확인한다.
95+
4. PR 댓글에 `@codex review`를 작성해 리뷰를 요청한다.
96+
5. 운영 방식이 안정되면 Automatic reviews 적용을 검토한다.
97+
98+
참고:
99+
100+
- [Codex code review in GitHub](https://developers.openai.com/codex/integrations/github)
101+
- [Codex Code Review 설정](https://chatgpt.com/codex/settings/code-review)
102+
103+
## 6. 작업별 실행 흐름
104+
105+
### 6.1 작업 정의
106+
107+
Issue 또는 작업 문서에 문제와 성공 조건을 먼저 작성한다.
108+
109+
```markdown
110+
## 문제
111+
112+
어떤 기능에서 어떤 비용이나 실패 가능성이 발생하는가
113+
114+
## 성공 조건
115+
116+
- 변경 후 지켜야 할 동작
117+
- 반드시 통과해야 할 테스트
118+
- 유지해야 할 API 또는 데이터 계약
119+
120+
## 제외 범위
121+
122+
- 이번 작업에서 변경하지 않을 영역
123+
```
124+
125+
이 단계의 목적은 AI가 해결해야 할 문제와 해결하지 않아야 할 문제를 구분하는 것이다.
126+
127+
### 6.2 구조 분석 요청
128+
129+
구현 AI에게 파일 수정 없이 분석과 계획만 요청한다.
130+
131+
```text
132+
아직 구현하지 마.
133+
기존 구조를 분석하고 다음 내용을 먼저 정리해줘.
134+
135+
- 문제 원인
136+
- 변경이 필요한 파일과 책임
137+
- API, 데이터베이스, 호환성 영향
138+
- 필요한 테스트
139+
- 예상 리스크
140+
- 이번 작업에서 제외할 범위
141+
```
142+
143+
산출물:
144+
145+
- 변경 계획
146+
- 영향 범위
147+
- 테스트 계획
148+
- 리스크 목록
149+
150+
### 6.3 사람의 계획 검토와 승인
151+
152+
사람은 AI 계획을 다음 기준으로 검토한다.
153+
154+
- 문제 원인이 정확한가
155+
- 변경 범위가 과도하지 않은가
156+
- 기존 설계 원칙과 충돌하지 않는가
157+
- 더 단순한 대안이 있는가
158+
- 트랜잭션 경계와 실패 경로를 고려했는가
159+
- 검증 방법이 충분한가
160+
161+
계획을 그대로 승인할 필요는 없다. 수정하거나 기각한 내용과 이유가 중요한 판단 근거가 된다.
162+
163+
승인 예시:
164+
165+
```text
166+
조회 API 응답 계약은 유지하고 Graph 조회는 제외해.
167+
Domain Event Outbox와 Read Model 변경만 이 계획으로 구현해줘.
168+
계획 밖의 변경이 필요하면 수정 전에 설명해줘.
169+
```
170+
171+
### 6.4 구현
172+
173+
구현 AI는 승인된 계획 안에서만 파일을 수정한다.
174+
175+
- 계획에서 벗어나는 변경이 필요하면 먼저 이유와 영향을 설명한다.
176+
- 관련 없는 리팩터링과 서식 변경은 하지 않는다.
177+
- 기존 사용자 변경을 되돌리지 않는다.
178+
- 테스트가 필요한 변경은 검증 코드와 함께 구현한다.
179+
180+
산출물:
181+
182+
- 코드 변경
183+
- 테스트 코드
184+
- 계획과 달라진 내용의 설명
185+
186+
### 6.5 로컬 검증
187+
188+
구현 후에는 변경 위험에 맞는 검증을 수행한다.
189+
190+
- 컴파일
191+
- 단위 테스트
192+
- 통합 테스트
193+
- API 계약 확인
194+
- 데이터 마이그레이션 영향 확인
195+
- 성능 주장이 있다면 측정 결과 확인
196+
197+
테스트를 실행하지 못했다면 이유와 남은 리스크를 명시한다.
198+
199+
### 6.6 PR 작성
200+
201+
브랜치를 push하고 PR을 만든다. PR에는 AI 사용 자체보다 사람의 판단과 검증 결과를 기록한다.
202+
203+
```markdown
204+
## AI 보조 작업 기록
205+
206+
- 사용 범위: 기존 구조 분석, 구현 계획, 테스트 누락 검토
207+
- 채택한 제안과 이유: 변경 이벤트를 Outbox에 저장해 후속 작업을 재시도할 수 있도록 함
208+
- 기각한 제안과 이유: 요청 시점 이중 쓰기는 부분 실패 복구가 어려워 제외
209+
- 실행한 검증: 통합 테스트, 중복 이벤트 테스트
210+
- 남은 리스크: 최종적 일관성으로 인한 조회 반영 지연
211+
```
212+
213+
### 6.7 독립 리뷰
214+
215+
GitHub PR 댓글에 다음과 같이 리뷰를 요청한다.
216+
217+
```text
218+
@codex review
219+
```
220+
221+
특정 관점이 필요하면 리뷰 범위를 명시한다.
222+
223+
```text
224+
@codex review for transaction boundaries, event duplication, and missing tests
225+
```
226+
227+
리뷰 AI는 PR diff와 저장소 `AGENTS.md`의 리뷰 기준을 바탕으로 문제를 찾는다. 리뷰 중에는 코드를 직접 수정하지 않는다.
228+
229+
### 6.8 리뷰 의견 판단
230+
231+
사람은 리뷰 의견을 무조건 반영하지 않는다.
232+
233+
- 실제 오류인가
234+
- 기존 요구사항과 충돌하지 않는가
235+
- 복잡도를 불필요하게 높이지 않는가
236+
- 추가 테스트로 확인할 수 있는가
237+
238+
채택하거나 기각한 의견과 이유를 PR에 남긴다.
239+
240+
### 6.9 수정과 최종 검증
241+
242+
채택한 리뷰 의견만 별도 구현 작업으로 반영한다.
243+
244+
1. 리뷰 의견의 수정 범위를 정의한다.
245+
2. 구현 AI가 수정한다.
246+
3. 관련 테스트를 다시 실행한다.
247+
4. 필요하면 `@codex review`를 다시 요청한다.
248+
5. 사람이 최종 diff와 테스트 결과를 확인한 뒤 merge한다.
249+
250+
## 7. 자동화와 사람의 판단 경계
251+
252+
| 단계 | 자동화 가능 여부 | 최종 책임 |
253+
| --- | --- | --- |
254+
| 기존 구조 분석 | 가능 | 사람 |
255+
| 변경 계획 작성 | 가능 | 사람 |
256+
| 계획 승인 | 자동화하지 않음 | 사람 |
257+
| 코드 구현 | 가능 | 사람 |
258+
| 테스트 실행 | 가능 | 사람 |
259+
| PR 리뷰 요청 | 자동화 가능 | 사람 |
260+
| 리뷰 의견 채택과 기각 | 자동화하지 않음 | 사람 |
261+
| merge 결정 | 자동화하지 않음 | 사람 |
262+
263+
Human Approval Gate는 사람이 계획과 리뷰 결과를 실제로 판단할 때 의미가 있다. 단순히 승인 버튼을 누르는 절차로 만들지 않는다.
264+
265+
## 8. 단계별 확장 계획
266+
267+
### 1단계: 수동 워크플로우 검증
268+
269+
- 최소 3건의 PR에서 계획 승인, 구현, PR 리뷰, 판단 기록 흐름을 반복한다.
270+
- 실제로 필요한 기록 항목과 불필요한 항목을 구분한다.
271+
272+
### 2단계: 리뷰 자동화 검토
273+
274+
- 수동 `@codex review`가 안정적으로 동작하면 Automatic reviews 적용을 검토한다.
275+
- 자동 리뷰가 사소한 문제보다 운영 리스크를 우선하도록 `AGENTS.md` 리뷰 기준을 조정한다.
276+
277+
### 3단계: Logging Hook 구축
278+
279+
- Codex Hook으로 도구 실행과 검증 흐름을 작업 단위로 기록한다.
280+
- 원본 로그는 Git에 커밋하지 않고 사람이 검토한 요약만 PR에 연결한다.
281+
- 상세 계획은 [`logging-hook-reproducibility-plan.md`](logging-hook-reproducibility-plan.md)를 따른다.
282+
283+
### 4단계: 검증 재현성 확인
284+
285+
- 작업 시작 commit과 검증 명령을 연결한다.
286+
- 다른 사람이 같은 기준점에서 검증 명령을 다시 실행할 수 있는지 확인한다.
287+
- 로그를 이용해 변경 원인이나 검증 누락을 찾은 사례를 남긴다.

0 commit comments

Comments
 (0)