05 메모리 & 지식 Markdown

WORKLOG & Failure Learning

시간순 작업 스냅샷과 실패 학습 문서를 분리 관리 — agent-retro 라벨 체계와 FAILURE_LOG/CASEBOOK 기준

Source: src/content/docs/worklog-and-failure-learning.md
Order: 62

한눈에 보기

작업 맥락이 세션 사이에서 사라지지 않도록, 시간순 WORKLOG와 실패 학습 문서를 분리해 관리하는 운영 규칙입니다. 에이전트 작업 회고에 쓰는 라벨 체계도 함께 정의합니다.

핵심 질문: 같은 실패를 반복하지 않으려면 무엇을 어디에 어떤 형식으로 남겨야 하는가?
읽는 대상: 에이전트 작업 기록과 실패 학습 체계를 만들려는 운영자
연결 문서: Memory & Documentation Policy, Retrospective Loop, Self-Improving Knowledge Loop

목적

프로젝트 진행 맥락을 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
날짜가 바뀌면 새 파일 생성
세션 시작 전에 빈 파일을 미리 만들지 않는다
세션 종료 때 한 번 몰아서 쓰지 말고, 의미 있는 단계 완료 직후 기록한다
Memory Bank로 충분한 단순 대화 맥락은 WORKLOG에 복제하지 않는다

권장 포맷

# 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, 테스트, 장애 문서)
실패했다면 증상보다 우회/교훈까지
다음 세션의 행동이나 프로젝트 정본 문서에 영향을 주는 내용

Agent Usage Labels

에이전트 사용 경험을 메모리뱅크와 WORKLOG에 남길 때는 라벨을 최소 3개 붙인다. 슬래시 명령어 /agent-retro를 사용하면 아래 라벨과 템플릿을 기준으로 회고 블록을 생성한다.

결과 라벨 1개
성공 요인 또는 실패 원인 라벨 1개 이상
다음 행동 라벨 1개

라벨은 모두 소문자 kebab-case를 사용한다.

결과 라벨

라벨	의미
`agent-outcome:success`	목표 달성, 검증 통과, 재사용할 가치 있음
`agent-outcome:partial`	핵심 진척은 있었지만 남은 검증/수정 존재
`agent-outcome:blocked`	외부 의사결정, 권한, 환경 문제로 중단
`agent-outcome:failed`	접근 방식이 틀렸거나 재작업 필요
`agent-outcome:invalidated`	완료처럼 보였지만 이후 검증에서 잘못된 성공으로 판명

실행 방식 라벨

라벨	의미
`agent-mode:direct`	메인 에이전트가 직접 처리
`agent-mode:single-worker`	단일 worker/subagent 위임
`agent-mode:parallel-workers`	여러 worker를 파일/역할 경계로 병렬 위임
`agent-mode:review-only`	구현 없이 리뷰/분석만 수행
`agent-mode:bugfix-loop`	실패 로그 기반 수정-검증 반복
`agent-mode:cross-review`	Claude/Codex 또는 복수 관점 교차 리뷰

성공 요인 라벨

라벨	의미
`agent-success:clear-acceptance`	완료 조건과 검증 기준이 명확했음
`agent-success:small-scope`	범위가 작고 되돌리기 쉬웠음
`agent-success:file-ownership`	에이전트별 수정 가능 파일 경계가 명확했음
`agent-success:existing-pattern-reused`	기존 코드/문서 패턴을 재사용했음
`agent-success:parallel-review`	코드 재사용/품질/일관성 등 관점 분리 리뷰가 효과적이었음
`agent-success:independent-qa`	구현자와 다른 주체가 독립 검증했음
`agent-success:fast-feedback`	타입체크, lint, 테스트, hook이 빠르게 실패를 드러냈음
`agent-success:memory-recall`	메모리뱅크의 과거 결정/패턴이 작업 품질을 높였음

실패 원인 라벨

라벨	의미
`agent-failure:ambiguous-scope`	요청 범위나 완료 기준이 모호했음
`agent-failure:missing-context`	필요한 기존 문서/코드/결정 확인이 빠졌음
`agent-failure:wrong-file-boundary`	에이전트가 수정하면 안 되는 파일을 건드렸거나 충돌했음
`agent-failure:verification-skipped`	테스트, 브라우저 확인, 빌드 등 검증이 빠졌음
`agent-failure:test-gap`	테스트가 실제 실패 조건을 잡지 못했음
`agent-failure:over-refactor`	필요한 수정 범위를 넘어 리팩터링이 커졌음
`agent-failure:tool-env`	셸, 경로, 인코딩, 의존성, 권한 등 환경 문제
`agent-failure:user-change-collision`	사용자의 미커밋 변경 또는 병렬 작업과 충돌
`agent-failure:stale-handoff`	오래된 SESSION/WORKLOG/HANDOFF를 신뢰했음
`agent-failure:false-success`	성공 보고와 실제 런타임/QA 결과가 달랐음

다음 행동 라벨

라벨	의미
`agent-next:reuse`	같은 조건에서 이 방식 재사용
`agent-next:promote-rule`	반복 가능성이 높아 규칙/가이드로 승격
`agent-next:add-hook`	자동 차단/검증 hook 후보
`agent-next:add-test`	테스트 또는 QA 시나리오 추가 필요
`agent-next:write-casebook`	여러 프로젝트에 적용 가능한 교훈으로 casebook 반영
`agent-next:human-review`	다음에는 사람 확인이 필요한 영역
`agent-next:avoid-pattern`	같은 방식 재사용 금지

메모리뱅크 기록 템플릿

성공 케이스:

[agent-retro]
labels: agent-outcome:success, agent-mode:parallel-workers, agent-success:parallel-review, agent-next:reuse
context: 어떤 작업이었는가
worked: 무엇이 효과적이었는가
evidence: 어떤 검증/결과로 성공을 확인했는가
reuse_when: 어떤 조건에서 다시 쓸 것인가

실패 케이스:

[agent-retro]
labels: agent-outcome:failed, agent-mode:bugfix-loop, agent-failure:verification-skipped, agent-next:add-test
context: 어떤 작업이었는가
expected: 기대한 결과
actual: 실제 결과
root_cause: 실패 원인
prevention: 다음에 막는 방법

부분 성공/중단 케이스:

[agent-retro]
labels: agent-outcome:partial, agent-mode:single-worker, agent-success:existing-pattern-reused, agent-next:human-review
context: 어떤 작업이었는가
done: 완료된 것
remaining: 남은 것
decision_needed: 사람 판단이 필요한 지점

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을 우선 신뢰”

세션 운영 요약

세션 시작:

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

세션 종료:

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

Source Notes

이 문서는 KeystoneHub 규칙 원천의 WORKLOG and Failure Learning 가이드를 공개용으로 정리한 것입니다. 예시의 파일 경로와 코드 조각은 일반화된 샘플입니다. Provenance: keystone-native.