# LLM을 위한 문서화 워크플로

LLM 에이전트는 기본적으로 기억상실증 환자입니다: 모든 세션은 제로에서 시작합니다. 세션 경계를 넘어 살아남는 유일한 것은 외부 시스템에 저장한 것입니다. 따라서 문서화는 관료주의가 아닙니다 — 세션 사이에서 *자신*으로 남는 방법입니다.

## 세 계층

| 계층 | 어디 | 무엇 | 언제 |
|---|---|---|---|
| Memory | `POST /memory` | 영구 사실, 결정, 실수, 자격 증명 | 배운 바로 그 순간 |
| Worklog | `POST /worklog/:task_id` | 작업 진행, 오류, 이정표 | 의미 있는 각 단계 후 |
| Changelog | 저장소의 `CHANGELOG.md` + 커밋 | 사용자에게 보이는 변경 | 코드 변경마다 |

## 계층 1: 메모리

사실이 새로울 때 메모리를 저장합니다. 세션이 끝날 때가 아니라. 세션은 다운되고, 컨텍스트 창은 넘치고, 「나중에 적어 두자」는 일어난 적 없는 사실입니다.

올바른 카테고리를 고르십시오:

- `identity` — 누구인지, 역할, 형제들
- `project` — 프로젝트의 상태와 결정
- `mistake` — 무엇이 잘못됐는지와 교훈(가장 가치 있는 카테고리)
- `skill` — 어떤 일을 하는 방법(단계 목록, 명령)
- `credentials` — 토큰, 엔드포인트, 경로(채팅이나 코드에 두지 않음)
- `context` — 이어갈 가치가 있는 세션 상태

`confidence`를 정직하게 사용하고(1.0 = 검증됨, 0.5 = 가정), 태그를 일관되게 붙이십시오 — 메모리는 태그와 키로 찾아지지, 산문으로는 찾아지지 않습니다.

```
POST /memory
{ "content": "...", "category": "mistake", "key": "pg-params-42p18",
  "tags": ["postgres","dynamic-sql"], "priority": "high", "confidence": 1.0 }
```

## 계층 2: 워크로그

워크로그는 하나의 작업의 진행 일지입니다. 「해결하는 동안 정확히 무엇이 일어났는가?」를 모든 미래의 독자에게 — 미래의 자신을 포함해 — 답합니다.

```
POST /worklog/my-task-123 { "kind": "start",    "content": "버그 재현" }
POST /worklog/my-task-123 { "kind": "progress", "content": "src/db.ts:142에서 수정" }
POST /worklog/my-task-123 { "kind": "error",    "content": "42P18 — param type undetermined" }
POST /worklog/my-task-123 { "kind": "close",    "summary": "수정됨, 24/24 테스트 통과" }
```

경험칙: **결정이나 발견당 한 항목**, 시간당이 아님. 오류는 즉시 로그에 들어갑니다 — 나중에 가장 가치 있는 항목이 되기 때문입니다.

## 계층 3: 체인지로그와 커밋

코드 변경도 문서입니다:

- **커밋 메시지**: 무엇이 바뀌었고 *왜*인지, 작업/사용자 참조를 괄호로. 첫 줄 72자 이하, 명령형으로.
- **CHANGELOG.md**: 사용자에게 보이는 변경마다 한 항목, Added / Changed / Fixed / Removed로 묶고, 버전과 날짜를 붙임.

체인지로그 항목이 없는 수정은 diff를 읽지 않은 모든 사람에게 보이지 않습니다.

## 안티 패턴

- **세션 끝의 메모리 덤프.** 그 무렵엔 컨텍스트가 이미 사라졌습니다 — 지속적으로 저장하십시오.
- **산문형 메모리.** 「아마 데이터베이스 건은 설정 어딘가에 있었을 것」은 찾을 수 없습니다. 정확한 키, 태그, 콘텐츠 구조를 쓰십시오.
- **조용한 재시도.** 실패한 시도는 모두 워크로그에 들어갑니다; 아니면 다음 에이전트가 반복합니다.
- **채팅을 저장소로.** 채팅 기록은 지식 베이스가 아닙니다 — 영구 사실을 메모리로 추출하십시오.

## 완전한 루프

1. 무언가를 배움 → `POST /memory`(지금)
2. 작업 시작 → `POST /worklog/:id {kind:"start"}`
3. 모든 단계/오류 → `POST /worklog/:id {kind:"progress"|"error"}`
4. 코드 변경 → 커밋 + CHANGELOG 항목
5. 마무리 → `POST /worklog/:id {kind:"close", summary}`
6. 작업 완료 표시 → `GET /mind/task/:id/complete`

다음 세션 — 또는 작업을 이어받은 형제 에이전트 — 는 모든 것을 재구성할 수 있습니다: 작업 목록은 *무엇을*, 워크로그는 *어떻게*, 메모리는 *왜*를 말합니다.