| name | ai-session-ops |
| description | AI 세션 운영 규칙. 세션 시작/종료 절차, 문서 읽기 순서, 세션 로그, 완료 보고, 토큰 절약 전략, 스프린트 핸드오프, 다중 에이전트 역할 분리를 적용. AI와 협업하는 모든 프로젝트에서 사용. |
AI Session Operations (AI 세션 운영)
AI(Claude, Codex 등)가 프로젝트에서 세션 단위로 작업할 때의 표준 운영 절차.
기술 스택과 무관하게 모든 프로젝트에 적용한다.
1. 세션 시작 프로토콜
새 세션을 시작할 때 반드시 아래 순서로 문서를 읽는다.
읽기 순서
1. 루트 CLAUDE.md → 프로젝트 전체 규칙 파악
2. master-plan.md → 현재 상태, 로드맵, 우선순위 파악
3. project-context.md → 도메인/비즈니스 맥락 이해
4. 최신 스프린트 보고서 → 직전 작업 내역 확인
5. 코딩 가이드라인 → 구현 규칙 확인
6. 해당 폴더 CLAUDE.md → 작업할 영역의 세부 규칙 확인
컨텍스트 허브 구조
프로젝트에 ai-context/ (또는 유사한 협업 문서 허브)가 있다면:
ai-context/
├── START-HERE.md ← 빠른 참조 인덱스
├── master-plan.md ← Source of Truth (로드맵, 상태)
├── project-context.md ← 도메인/비즈니스 맥락
├── {role}-coding-guideline.md ← AI 역할별 구현 규칙
├── logs/ ← 세션별 작업 로그 (append-only)
│ └── YYYY-MM-DD-session-log.md
└── archive/ ← 완료된 스프린트 보고서
└── YYYY-MM-DD/
규칙
START-HERE.md가 있으면 가장 먼저 읽는다- 인덱스 파일이 없으면 위 읽기 순서를 따른다
- 경로는 항상 레포 루트 기준 상대경로 사용
2. 작업 원칙
필수 원칙
- 파일 직접 읽기: 수정 전 반드시 Read 도구로 파일 내용을 직접 읽는다. 절대 파일 내용을 추측하지 않는다
- 코드 재사용 우선: 기존 코드(타입/훅/함수/API)를 Grep/Glob으로 먼저 검색하고 재사용한다. 중복 구현 금지
- CLAUDE.md 우선 확인: 코딩 시작 전 해당 폴더의 CLAUDE.md를 먼저 읽는다
- 추측 금지: 확실하지 않은 것은 파일을 직접 읽거나 사용자에게 질문한다
- 하드코딩 회피: 문자열은 가능한 한 분리 가능한 구조(i18n, 상수, 환경변수)로 유지
3. 토큰 절약 전략
컨텍스트 윈도우를 효율적으로 사용하기 위한 문서 관리 전략.
작업 중 (세션 진행)
sprint-handoff-*.md 최신화logs/YYYY-MM-DD-session-log.md에 append- 이 두 파일만 갱신, 다른 공용 문서는 건드리지 않음
마감 시 (스프린트/마일스톤 종료)
master-plan.md 일괄 반영worklog.md, review-log.md 등 공용 문서 1회 정리- 커밋 ID와 작업 항목은 session log에서 공용 문서로 복사
아카이브 규칙
- 완료된 문서는
archive/{YYYY-MM-DD}/로 이동
- 아카이브 문서는 이력 추적이 필요할 때만 열기
- 작업 중인 세션에서 아카이브를 일상적으로 열지 않음
4. 세션 로그 템플릿
# Session Log YYYY-MM-DD
## 세션 정보
- 시작: HH:MM
- 목표: (이번 세션의 목표)
## 작업 항목
- [ ] 항목 1
- [ ] 항목 2
- [x] 완료된 항목
## 변경 내역
| 시간 | 파일 | 변경 내용 | 커밋 |
|------|------|-----------|------|
| HH:MM | `경로/파일.ts` | 변경 설명 | abc1234 |
## 이슈/블로커
- (발견한 이슈나 블로커)
## 메모
- (다음 세션을 위한 메모)
5. 완료 보고 형식
작업 완료 시 아래 형식으로 보고한다.
## 변경 요약
1. **변경 파일**: 수정/생성/삭제된 파일 목록
2. **핵심 로직**: 무엇을 왜 변경했는지 간결하게
3. **영향 범위**: 이 변경이 영향을 미치는 다른 부분
## 검증
1. **실행 명령**: 실행한 빌드/테스트 명령
2. **결과**: 성공/실패 + 출력 요약
3. **로그 위치**: 실패 시 로그 파일 경로
## 리스크 / 후속 작업
- 알려진 리스크나 주의사항
- 다음에 해야 할 작업
6. 스프린트 핸드오프 템플릿
스프린트 종료 시 다음 세션/에이전트를 위한 인수인계 문서.
# Sprint Handoff — Sprint X.Y (YYYY-MM-DD)
## 완료 항목
1. (완료된 기능/작업)
2. ...
## 미완료 / 이월 항목
1. (이월 사유와 함께)
2. ...
## 알려진 이슈
| 심각도 | 설명 | 관련 파일 |
|--------|------|-----------|
| HIGH | 설명 | `파일 경로` |
## 다음 스프린트 권장 사항
1. 우선 처리할 것
2. 주의할 것
3. 기술 부채
## 참조 커밋
- `abc1234` — 설명
- `def5678` — 설명
7. 다중 에이전트 협업
두 개 이상의 AI 에이전트가 협업할 때의 역할 분리.
역할 정의
| 역할 | 담당 | 산출물 |
|---|
| 구현자 (예: Claude) | 기능 구현, 코드 작성 | 코드 + 완료 보고 |
| 리뷰어 (예: Codex) | 코드 리뷰, 리스크 검증 | 리뷰 기록 + 머지 판정 |
구현자 규칙
- 문서 기준 우선순위에 따라 기능을 끝까지 구현
- 작업 완료 시 완료 보고 형식으로 보고
- 세션 로그에 모든 변경 사항 기록
리뷰어 규칙
- 검토 우선순위: 동작 오류 → 데이터 정합성 → UX 회귀 → 구조 일관성 → 테스트 누락
- 리뷰 완료 즉시 review-log에 누적 기록
- 동일 이슈 재발 시 "재발" 표기 + 원인 추적 메모
핸드오프 흐름
구현자 작업 완료
→ 완료 보고 작성
→ 스프린트 핸드오프 작성
→ 리뷰어가 핸드오프 + 코드 확인
→ 리뷰 기록 작성
→ 머지 판정
8. 문서 관리 규칙
| 규칙 | 설명 |
|---|
| 경로 | 항상 레포 루트 기준 상대경로 |
| 작업 중 갱신 | session log + sprint handoff만 |
| 마감 시 갱신 | master-plan + 공용 문서 일괄 |
| 아카이브 | 완료된 문서는 archive/{날짜}/로 이동 |
| 커밋 매핑 | 커밋 ID를 session log에 먼저 기록 → 마감 시 공용 문서 반영 |
| 주석 언어 | 프로젝트 규칙에 따름 (한국어 또는 영어) |
