WORKLOG and Failure Learning

프로젝트 진행 맥락을 `INTENT.md`/`SESSION.md`만으로 놓치지 않도록, 시간순 작업 스냅샷과 실패 학습 문서를 분리해 관리한다.

목적

프로젝트 진행 맥락을 INTENT.md/SESSION.md만으로 놓치지 않도록, 시간순 작업 스냅샷과 실패 학습 문서를 분리해 관리한다.

문서 역할 분리

문서	역할	질문 예시
INTENT.md	이번 작업의 목표/범위/검증 기준	"이번 작업에서 뭘 하기로 했지?"
SESSION.md	세션 handoff, 막힘, 다음 행동	"다음 세션에서 어디부터 이어야 하지?"
WORKLOG/YYYY/MM/YYYY-MM-DD-keyword.md	시간순 작업 스냅샷	"오늘 무엇을 바꿨고 어떤 판단을 했지?"
FAILURE_LOG.md	반복 실패 패턴 ledger	"같은 문제가 반복되고 있나?"
docs/guide/AI_AGENT_FAILURE_CASEBOOK.md	일반화 가능한 실패 교훈/운영 플레이북	"다음에는 어떤 방식으로 행동해야 하나?"

WORKLOG 규칙

• 경로: WORKLOG/YYYY/MM/YYYY-MM-DD-keyword.md
• 같은 날은 기존 파일에 append
• 날짜가 바뀌면 새 파일 생성
• 세션 시작 전에 빈 파일을 미리 만들지 않는다
• 세션 종료 때 한 번 몰아서 쓰지 말고, 의미 있는 단계 완료 직후 기록한다

권장 포맷

복사# 2026-04-01
#backend #auth #refactor

## 14:20 — Prisma service 정리
- 커넥션 생성 책임을 서비스로 고정
- 관련: `INTENT.md`, `docs/design/auth/DESIGN.md`

## 15:05 — 타입 에러 수정
- nullable 처리 누락 수정
- 관련: `FAILURE_LOG.md`

WORKLOG에 꼭 남길 것

• 무엇을 바꿨는지보다 왜 그렇게 결정했는지
• 다음 단계가 자연스럽게 이어지도록 하는 상태 정보
• 관련 문서 링크 (INTENT.md, DESIGN.md, PR, 테스트, 장애 문서)
• 실패했다면 증상보다 우회/교훈까지

FAILURE_LOG vs CASEBOOK

FAILURE_LOG.md

아래에 해당하면 여기에 기록한다.

• 동일 오류가 2회 이상 반복됨
• 같은 파일/도메인/에러 유형에서 재발 조짐이 있음
• 방지책을 체크리스트처럼 추적해야 함

기록 예:

복사## FL-012: auth null-check 누락
- 상태: Open
- 발생일: 2026-04-01
- 영향 파일: src/auth/useSession.ts
- 증상: 로그인 직후 null 접근으로 화면 깨짐
- 근본 원인: optional 응답 계약 누락
- 방지책: null-guard를 기본 체크리스트에 포함

docs/guide/AI_AGENT_FAILURE_CASEBOOK.md

아래에 해당하면 여기에 기록한다.

• 여러 프로젝트에서 재사용 가능한 교훈
• 툴링 함정, 인코딩/BOM, 경로/셸 차이 같은 운영 이슈
• 문서 append 위치, 세션 시작 점검 순서 같은 작업 습관 교정

예:

• "PowerShell에서는 되지만 Git Bash SSH에서 BOM 때문에 실패"
• "WORKLOG append 전에 하단 참고 블록 위치 확인 필요"
• "과거 대화보다 최신 WORKLOG/SESSION을 우선 신뢰"

세션 운영 요약

세션 시작:

1. SESSION.md 확인
2. 최신 WORKLOG 1개 확인
3. INTENT.md 확인
4. 필요 시 FAILURE_LOG.md와 casebook 확인

세션 종료:

1. SESSION.md handoff 갱신
2. 의미 있는 진척이 있으면 WORKLOG append
3. 반복 실패면 FAILURE_LOG.md 갱신
4. 일반화 가능한 교훈이면 casebook 반영