ai-session-ops

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. 작업 원칙

필수 원칙

1. 파일 직접 읽기: 수정 전 반드시 Read 도구로 파일 내용을 직접 읽는다. 절대 파일 내용을 추측하지 않는다
2. 코드 재사용 우선: 기존 코드(타입/훅/함수/API)를 Grep/Glob으로 먼저 검색하고 재사용한다. 중복 구현 금지
3. CLAUDE.md 우선 확인: 코딩 시작 전 해당 폴더의 CLAUDE.md를 먼저 읽는다
4. 추측 금지: 확실하지 않은 것은 파일을 직접 읽거나 사용자에게 질문한다
5. 하드코딩 회피: 문자열은 가능한 한 분리 가능한 구조(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에 먼저 기록 → 마감 시 공용 문서 반영
주석 언어	프로젝트 규칙에 따름 (한국어 또는 영어)