Docs: AI 활용 흐름과 Codex 작업 지침 정리

AGENTS.md

@@ -1,8 +1,8 @@
 # AGENTS.md
 
-이 저장소에서 AI 보조 개발을 수행할 때 따르는 규칙입니다.
+이 저장소에서 AI 보조 개발을 수행할 때 따르는 실행 규칙입니다.
 
-상세 작업 흐름: [`ai/ai-assisted-development-workflow.md`](ai/ai-assisted-development-workflow.md)
+AI가 따라야 할 규칙은 이 파일을 기준으로 합니다. `ai/ai-assisted-development-workflow.md`는 AI 활용 흐름을 기록하고 개선하기 위한 워크플로우 정리본이고, `ai/ai-usage-guide.html`은 사람이 AI 활용 흐름을 이해하기 위한 설명 문서입니다. 문서 간 내용이 충돌하면 이 `AGENTS.md`를 우선합니다.
 
 ## 구현 전 계획
 
@@ -15,6 +15,13 @@
   - 예상 리스크와 의도적으로 제외할 범위
 - 사용자가 즉시 구현을 명시적으로 요청하지 않았다면 승인 후 파일을 수정한다.
 
+## Superpowers 사용
+
+- 기능 추가, 리팩터링, 버그 수정, 운영 구조 변경처럼 판단이 필요한 작업은 관련 Superpowers skill을 먼저 확인하고 적용한다.
+- 사용자가 Superpowers 또는 특정 skill 사용을 명시하면 해당 skill 지침을 따른다.
+- 단순 조회, 상태 확인, 사용자가 명시한 일회성 명령 실행에는 불필요하게 긴 Superpowers 절차를 적용하지 않는다.
+- Superpowers 지침과 이 저장소 규칙이 충돌하면 사용자 지시와 이 `AGENTS.md`를 우선한다.
+
 ## 문서 작성 언어
 
 - 저장소에 추가하는 문서, 설계안, 구현 계획, 리뷰 요약은 한국어로 작성한다.
@@ -32,6 +39,37 @@
 - 커밋이 필요해 보이면 먼저 변경 범위와 추천 커밋 메시지를 제안한다.
 - 사용자가 직접 커밋하거나 push하겠다고 말한 경우에는 명령을 실행하지 않고 필요한 확인 정보만 제공한다.
 
+## Branch naming
+
+- 브랜치를 만들 때는 사용자가 지정한 브랜치명을 우선한다.
+- 별도 지정이 없으면 기존 저장소의 브랜치 네이밍 관례를 확인하고 따른다.
+- 이 저장소에서는 기본적으로 `feat/`, `fix/`, `refactor/`, `docs/`, `test/` 같은 작업 유형 prefix를 사용한다.
+- `codex/` prefix는 사용자가 명시적으로 요청한 경우에만 사용한다.
+
+## GitHub Issue 작성
+
+- 구조 변경, 운영 리스크, API/DB 계약 영향, 여러 파일이나 서비스에 걸친 변경, 성능 주장처럼 사전 합의가 필요한 작업은 먼저 이슈를 작성하거나 기존 이슈를 확인한다.
+- 오타 수정, 작은 테스트 보강, 영향 범위가 명확한 단일 파일 수정은 사용자가 요청하지 않는 한 이슈 없이 진행할 수 있다.
+- 이슈를 작성할 때는 `.github/ISSUE_TEMPLATE`의 해당 템플릿 구조를 따른다.
+- 이슈 제목은 기존 이슈의 접두사 형식(`Feat:`, `Fix:`, `Refactor:` 등)을 확인해 일치시킨다.
+- 라벨은 템플릿 파일의 문자열만 보고 새로 만들거나 지정하지 않는다. GitHub에 이미 존재하는 저장소 라벨 체계를 확인하고 기존 라벨을 사용한다.
+- 이슈 assignee는 별도 지시가 없으면 이슈 작성을 요청한 사람으로 지정한다.
+- 요청한 사람의 GitHub 계정을 확정할 수 없으면 assignee를 임의로 지정하지 말고 먼저 확인한다.
+
+## GitHub PR 작성
+
+- PR을 작성할 때는 `.github/PULL_REQUEST_TEMPLATE.md` 구조를 따른다.
+- PR 제목은 기존 PR, 연결 이슈, 브랜치 맥락의 접두사 형식(`Feat:`, `Fix:`, `Refactor:` 등)을 확인해 일치시킨다.
+- `Issue Number`에는 연결된 이슈 번호를 명시한다. 연결 이슈가 없다면 사유를 PR 본문에 간단히 남긴다.
+- `작업 내용`에는 단순 파일 목록이 아니라 무엇을 왜 변경했는지와 주요 동작 변화를 작성한다.
+- `Reference`에는 관련 이슈, 설계 문서, 측정 결과, 외부 근거가 있을 때만 추가한다.
+- AI를 사용했다면 `AI 보조 작업 기록` 섹션을 삭제하지 않고 사용 범위, 채택/기각한 제안, 실행한 검증, 남은 리스크를 작성한다.
+- AI를 사용하지 않았다면 템플릿 안내대로 `AI 보조 작업 기록` 섹션을 삭제할 수 있다.
+- `Check List`는 실제로 확인한 항목만 체크한다. 실행하지 않은 테스트나 확인하지 않은 브랜치/라벨 항목을 체크하지 않는다.
+- PR 라벨은 새로 만들지 말고 GitHub에 이미 존재하는 저장소 라벨 체계를 확인하고 사용한다.
+- PR assignee는 별도 지시가 없으면 PR 작성을 요청한 사람으로 지정한다.
+- 요청한 사람의 GitHub 계정을 확정할 수 없으면 assignee를 임의로 지정하지 말고 먼저 확인한다.
+
 ## 구현과 리뷰 분리
 
 - 구현 단계에서는 승인된 계획을 따르고 계획에서 벗어난 변경을 보고한다.
@@ -41,14 +79,17 @@
 ## Review guidelines
 
 Codex GitHub Code Review가 PR 리뷰에서 따라야 할 기준이다.
+아래 항목은 우선 확인해야 할 고위험 영역이며, 리뷰 범위를 이 목록으로 제한하지 않는다.
+전체 diff를 기준으로 기능 오류, 요구사항 불일치, 보안/권한 문제, 데이터 정합성, 운영 안정성, 누락된 테스트를 폭넓게 확인한다.
 
 - 리뷰 코멘트는 한국어로 작성한다.
 - 각 코멘트는 심각도, 문제 상황, 위험, 수정 방향을 짧게 포함한다.
+- 목록에 없는 명백한 버그, 회귀, 운영 리스크가 보이면 반드시 지적한다.
 - 트랜잭션 경계와 부분 실패 가능성을 확인한다.
 - 비동기 작업의 유실, 중복 처리, 재시도 경로를 확인한다.
 - API와 데이터베이스 호환성 회귀를 확인한다.
 - 누락된 테스트와 근거가 부족한 성능 주장을 확인한다.
-- AI 워크플로우 문서를 리뷰할 때는 과장된 성과 표현, 비밀 정보 노출 위험, 실제 구현 전 주장된 자동화 여부를 확인한다.
+- AI 활용 설명 문서를 리뷰할 때는 과장된 성과 표현, 비밀 정보 노출 위험, 실제 구현 전 주장된 자동화 여부를 확인한다.
 - 사소한 서식보다 기능 오류와 운영 리스크를 우선한다.
 
 ## 판단 기록

ai/README.md

@@ -4,7 +4,8 @@
 
 | 문서 | 역할 |
 | --- | --- |
-| [`ai-assisted-development-workflow.md`](ai-assisted-development-workflow.md) | 전체 작업 흐름과 단계별 산출물 |
+| [`ai-assisted-development-workflow.md`](ai-assisted-development-workflow.md) | AI 활용 흐름을 기록하고 개선하는 워크플로우 정리본 |
+| [`ai-usage-guide.html`](ai-usage-guide.html) | AI 활용 흐름과 판단 기준을 설명하는 사람용 HTML 문서 |
 | [`logging-hook-reproducibility-plan.md`](logging-hook-reproducibility-plan.md) | Logging Hook과 검증 재현성 구축 계획 |
 
-저장소 루트의 `AGENTS.md`는 AI가 따라야 할 실행 규칙이다. 이 폴더의 문서는 사람이 작업 방식과 판단 근거를 이해할 수 있도록 설명한다.
+저장소 루트의 `AGENTS.md`는 AI가 따라야 할 실행 규칙이다. `ai-assisted-development-workflow.md`는 AI 활용 흐름을 기록하고 개선하는 정리본이고, HTML 문서는 사람이 작업 방식과 판단 근거를 이해하기 위한 설명 문서이다.