Progress Log

---
description: '작업 청크 종료 시점의 .progress/날짜/주제.md 진행 기록'
allowed-tools: ['Bash', 'Read', 'Write', 'Edit', 'Glob']
---

## 인자

$ARGUMENTS

위 인자는 **주제 슬러그** (kebab-case). 예: `logging-components`, `wait-analysis-charts`, `deadrows-extraction`.

비어있으면 현재 대화 컨텍스트에서 핵심 주제 1-3단어 직접 추론 후 슬러그 결정. 예: 직전 "DeadRows 차트 비교"라면 `deadrows-chart-comparison`.

## 역할

방금까지의 대화 흐름을 `.progress/YYMMDD/<주제>.md` 마크다운으로 저장.

작업 결과뿐 아니라 **결정의 근거(Why)** 와 **고려했던 대안** 보존. 같은 패턴 재발 시 의사결정 비용 절감 목적.

## 실행 순서

### 1. 날짜 폴더 결정

```bash
date +%y%m%d
```

결과를 `.progress/YYMMDD/` 로 사용. 폴더 없으면 생성.

### 2. 파일 경로 결정

`.progress/YYMMDD/<주제>.md`.

기존 파일은 **Edit 으로 갱신** (해당 섹션 추가/수정), 신규 파일은 **Write 로 생성**.

### 3. 내용 작성

대화 컨텍스트에서 다음을 추출해 표준 섹션 구조로 정리:

#### 표준 섹션

```markdown
# <주제 한국어 제목>

## Context

이 작업이 왜 필요했는지. 트리거된 문제/요구. 1-3 문단.

## 결정 사항

핵심 의사결정. 각 항목은 **결정 + Why(근거) + 대안(있으면)** 구조.

- **{결정 요약}**
  - **Why**: {왜 이 선택? 어떤 제약/관찰이 이끌었는지}
  - **대안**: {버려진 옵션과 그 이유} (해당 시)

## 변경 사항

신규 / 변경 / 삭제 파일 간략 요약. 너무 자세하지 않게 — 디렉토리 단위 또는 핵심 파일만.

### 신규
- `path/to/new.ts` — 한 줄 설명

### 변경
- `path/to/changed.ts` — 무엇이 바뀌었는지

### 삭제
- `path/to/old.ts` (이유)

## 검증

작업 완료 확인 방법과 실제 결과. (tsc, lint, playwright, manual UI 등)

| 항목 | 결과 |
|---|---|
| `pnpm exec tsc --noEmit` | EXIT=0 |
| Performance > X UI | 정상 |
| Wait Analysis > X UI | 정상 |

## 학습 / 패턴 (있으면)

이번 작업에서 도출된 재사용 가능한 패턴, 안티패턴, 가이드라인.
이 섹션이 미래의 의사결정 비용을 가장 많이 줄임.

- **패턴**: {일반화 가능한 규칙}
- **안티패턴**: {해서 안 되는 것 + 왜}

## 다음 단계 (있으면)

이 작업에서 파생된 후속 작업.
```

### 4. 작성 원칙

- **사실 기반**: 대화에 등장하지 않은 내용을 만들어내지 않음. 모르면 빼거나 "확인 필요" 표기.
- **결정 근거 보존**: "X 로 결정함" 만 적지 말고 "X 로 결정한 이유는 Y 때문" 까지 적음.
- **버려진 대안 기록**: "Y 도 검토했지만 Z 이유로 X 선택" 같은 대조가 미래에 가치 큼.
- **상대 시간 → 절대 시간**: "오늘", "방금" 같은 표현 금지. 항상 날짜/시간으로 변환.
- **회의록 아님**: 대화 흐름을 그대로 옮기지 말고, 결과·결정·근거만 추출.
- **간결성**: 표/불릿 적극 사용. 산문 단락은 최소화.
- **링크 가능한 경로**: 파일 경로는 항상 풀 경로 (예: `apps/dbms/postgresql/src/...`).

### 5. 갱신 시 주의

기존 파일에 추가할 때:

- **중복 회피**: 이미 적힌 결정 사항 재기록 금지
- **섹션 순서 유지**: Context → 결정 → 변경 → 검증 → 학습 → 다음 단계
- **타임라인 표기 불필요**: 같은 주제 같은 날짜라면 "오전/오후" 같은 시간 분리 불필요
- 다른 주제로 변경된 흐름이면 **새 파일 생성** (같은 날짜 폴더 내 다른 슬러그)

### 6. 마무리 보고

작성 후 다음 형식으로 사용자 보고:

```
.progress/YYMMDD/<주제>.md {생성|갱신}.

핵심 정리:
- {핵심 결정 1}
- {핵심 결정 2}
- {핵심 결정 3}
```

## 안 하는 것

- **대화 전체 덤프 금지**: 회의록이 아니라 의사결정 기록
- **추측 금지**: 대화에 없는 검증 결과나 결정 사유 생성 금지
- **CLAUDE.md 규칙 중복 금지**: 코딩 컨벤션 등 기존 규칙 재기록 금지
- **TODO 나열 금지**: "다음 단계"는 명확한 작업 1-3개만, 모호한 위시리스트 제외