AI가 코드를 빠르게 생성하는 것보다 변경 범위와 리스크를 사람이 이해하고 검증할 수 있도록 관리하는 것을 목표로 한다.
이 워크플로우는 다음 질문에 답할 수 있어야 한다.
- AI는 어떤 범위에서 사용됐는가
- 구현 전에 어떤 영향과 리스크를 검토했는가
- 어떤 제안을 사람이 채택하거나 기각했는가
- 구현 결과는 별도 리뷰와 테스트를 거쳤는가
- 다른 사람이 변경 이유와 검증 방법을 다시 확인할 수 있는가
- AI는 구현 전에 기존 구조와 영향 범위를 분석한다.
- 사람은 계획을 검토하고 승인한다.
- AI는 승인된 범위 안에서만 구현한다.
- 구현과 리뷰는 다른 작업으로 분리한다.
- 사람은 리뷰 의견의 채택 여부를 최종 판단한다.
- 테스트 결과와 남은 리스크를 PR에 기록한다.
- 원본 로그보다 설명 가능한 판단과 검증 결과를 우선한다.
| 역할 | 책임 | 하지 않는 일 |
|---|---|---|
| 사람 | 문제 정의, 계획 승인, 제안 채택과 기각, 최종 검증 | AI 결과를 검토 없이 수용하지 않는다 |
| 구현 AI | 구조 분석, 계획 제안, 승인 범위 구현, 테스트 실행 | 승인 전 파일을 수정하지 않는다 |
| 리뷰 AI | diff 기반 오류, 회귀, 누락 테스트, 운영 리스크 검토 | 리뷰 중 코드를 직접 수정하지 않는다 |
| Logging Hook | 도구 실행과 검증 흐름 기록 | 코드 정확성이나 동일 결과 생성을 보장하지 않는다 |
구현 AI와 리뷰 AI는 같은 모델을 사용해도 된다. 다만 리뷰 AI는 구현 대화의 맥락보다 PR diff와 리뷰 기준을 중심으로 검토해야 한다.
| 항목 | 상태 | 근거 |
|---|---|---|
| 전역 AI 작업 원칙 | 적용 중 | ~/.codex/AGENTS.md |
| 저장소별 작업 규칙 | 적용 중 | AGENTS.md |
| AI 사용 판단 기록 | 적용 시작 | .github/PULL_REQUEST_TEMPLATE.md |
| 구현과 GitHub PR 리뷰 분리 | 적용 시작 | Codex GitHub Code Review |
| 도구 실행 Logging Hook | 계획 | logging-hook-reproducibility-plan.md |
| 검증 재현성 효과 측정 | 계획 | Hook과 PR 기록 누적 후 확인 |
전역 ~/.codex/AGENTS.md에는 모든 프로젝트에 공통으로 적용할 개인 원칙을 둔다.
- 구현 전 가정과 트레이드오프 확인
- 최소 범위 변경
- 관련 없는 코드 수정 금지
- 검증 가능한 성공 조건 정의
루트 AGENTS.md에는 Docsa에서 지킬 구체적인 규칙을 둔다.
- 구현 전 변경 파일과 영향 범위 제시
- 승인 전 파일 수정 금지
- API와 데이터베이스 호환성 검토
- 구현과 리뷰 역할 분리
- PR에 AI 사용 범위와 판단 기록
리뷰 기준은 Codex GitHub Code Review가 명확히 인식할 수 있도록 ## Review guidelines 섹션에 둔다.
- 리뷰 코멘트는 한국어로 작성한다.
- 사소한 서식보다 기능 오류, 데이터 정합성, 운영 리스크, 누락 테스트를 우선한다.
- AI 워크플로우 문서는 실제 구현 전 주장된 자동화나 과장된 효과 표현을 확인한다.
PR 템플릿에는 다음 내용을 기록한다.
## AI 보조 작업 기록
- 사용 범위:
- 채택한 제안과 이유:
- 기각한 제안과 이유:
- 실행한 검증:
- 남은 리스크:GitHub PR에서 구현과 리뷰를 분리하기 위해 Codex Code Review를 사용한다.
- Codex Cloud에 GitHub 저장소를 연결한다.
- Codex Code Review 설정에서 저장소의 Code review를 활성화한다.
- 처음에는 Automatic reviews를 끄고 수동 리뷰로 동작을 확인한다.
- PR 댓글에
@codex review를 작성해 리뷰를 요청한다. - 운영 방식이 안정되면 Automatic reviews 적용을 검토한다.
참고:
Issue 또는 작업 문서에 문제와 성공 조건을 먼저 작성한다.
## 문제
어떤 기능에서 어떤 비용이나 실패 가능성이 발생하는가
## 성공 조건
- 변경 후 지켜야 할 동작
- 반드시 통과해야 할 테스트
- 유지해야 할 API 또는 데이터 계약
## 제외 범위
- 이번 작업에서 변경하지 않을 영역이 단계의 목적은 AI가 해결해야 할 문제와 해결하지 않아야 할 문제를 구분하는 것이다.
구현 AI에게 파일 수정 없이 분석과 계획만 요청한다.
아직 구현하지 마.
기존 구조를 분석하고 다음 내용을 먼저 정리해줘.
- 문제 원인
- 변경이 필요한 파일과 책임
- API, 데이터베이스, 호환성 영향
- 필요한 테스트
- 예상 리스크
- 이번 작업에서 제외할 범위
산출물:
- 변경 계획
- 영향 범위
- 테스트 계획
- 리스크 목록
사람은 AI 계획을 다음 기준으로 검토한다.
- 문제 원인이 정확한가
- 변경 범위가 과도하지 않은가
- 기존 설계 원칙과 충돌하지 않는가
- 더 단순한 대안이 있는가
- 트랜잭션 경계와 실패 경로를 고려했는가
- 검증 방법이 충분한가
계획을 그대로 승인할 필요는 없다. 수정하거나 기각한 내용과 이유가 중요한 판단 근거가 된다.
승인 예시:
조회 API 응답 계약은 유지하고 Graph 조회는 제외해.
Domain Event Outbox와 Read Model 변경만 이 계획으로 구현해줘.
계획 밖의 변경이 필요하면 수정 전에 설명해줘.
구현 AI는 승인된 계획 안에서만 파일을 수정한다.
- 계획에서 벗어나는 변경이 필요하면 먼저 이유와 영향을 설명한다.
- 관련 없는 리팩터링과 서식 변경은 하지 않는다.
- 기존 사용자 변경을 되돌리지 않는다.
- 테스트가 필요한 변경은 검증 코드와 함께 구현한다.
산출물:
- 코드 변경
- 테스트 코드
- 계획과 달라진 내용의 설명
구현 후에는 변경 위험에 맞는 검증을 수행한다.
- 컴파일
- 단위 테스트
- 통합 테스트
- API 계약 확인
- 데이터 마이그레이션 영향 확인
- 성능 주장이 있다면 측정 결과 확인
테스트를 실행하지 못했다면 이유와 남은 리스크를 명시한다.
브랜치를 push하고 PR을 만든다. PR에는 AI 사용 자체보다 사람의 판단과 검증 결과를 기록한다.
## AI 보조 작업 기록
- 사용 범위: 기존 구조 분석, 구현 계획, 테스트 누락 검토
- 채택한 제안과 이유: 변경 이벤트를 Outbox에 저장해 후속 작업을 재시도할 수 있도록 함
- 기각한 제안과 이유: 요청 시점 이중 쓰기는 부분 실패 복구가 어려워 제외
- 실행한 검증: 통합 테스트, 중복 이벤트 테스트
- 남은 리스크: 최종적 일관성으로 인한 조회 반영 지연GitHub PR 댓글에 다음과 같이 리뷰를 요청한다.
@codex review
특정 관점이 필요하면 리뷰 범위를 명시한다.
@codex review for transaction boundaries, event duplication, and missing tests
리뷰 AI는 PR diff와 저장소 AGENTS.md의 리뷰 기준을 바탕으로 문제를 찾는다. 리뷰 중에는 코드를 직접 수정하지 않는다.
사람은 리뷰 의견을 무조건 반영하지 않는다.
- 실제 오류인가
- 기존 요구사항과 충돌하지 않는가
- 복잡도를 불필요하게 높이지 않는가
- 추가 테스트로 확인할 수 있는가
채택하거나 기각한 의견과 이유를 PR에 남긴다.
채택한 리뷰 의견만 별도 구현 작업으로 반영한다.
- 리뷰 의견의 수정 범위를 정의한다.
- 구현 AI가 수정한다.
- 관련 테스트를 다시 실행한다.
- 필요하면
@codex review를 다시 요청한다. - 사람이 최종 diff와 테스트 결과를 확인한 뒤 merge한다.
| 단계 | 자동화 가능 여부 | 최종 책임 |
|---|---|---|
| 기존 구조 분석 | 가능 | 사람 |
| 변경 계획 작성 | 가능 | 사람 |
| 계획 승인 | 자동화하지 않음 | 사람 |
| 코드 구현 | 가능 | 사람 |
| 테스트 실행 | 가능 | 사람 |
| PR 리뷰 요청 | 자동화 가능 | 사람 |
| 리뷰 의견 채택과 기각 | 자동화하지 않음 | 사람 |
| merge 결정 | 자동화하지 않음 | 사람 |
Human Approval Gate는 사람이 계획과 리뷰 결과를 실제로 판단할 때 의미가 있다. 단순히 승인 버튼을 누르는 절차로 만들지 않는다.
- 최소 3건의 PR에서 계획 승인, 구현, PR 리뷰, 판단 기록 흐름을 반복한다.
- 실제로 필요한 기록 항목과 불필요한 항목을 구분한다.
- 수동
@codex review가 안정적으로 동작하면 Automatic reviews 적용을 검토한다. - 자동 리뷰가 사소한 문제보다 운영 리스크를 우선하도록
AGENTS.md리뷰 기준을 조정한다.
- Codex Hook으로 도구 실행과 검증 흐름을 작업 단위로 기록한다.
- 원본 로그는 Git에 커밋하지 않고 사람이 검토한 요약만 PR에 연결한다.
- 상세 계획은
logging-hook-reproducibility-plan.md를 따른다.
- 작업 시작 commit과 검증 명령을 연결한다.
- 다른 사람이 같은 기준점에서 검증 명령을 다시 실행할 수 있는지 확인한다.
- 로그를 이용해 변경 원인이나 검증 누락을 찾은 사례를 남긴다.