---
name: devlog
description: 프로젝트 개발 이력을 Notion 페이지에 표준 포맷으로 누적 기록할 때 사용한다. 마일스톤 완료, 세션 마감, 중요 이슈(에러 해결, 설계 변경, 의사결정)가 생겼을 때와 "노션 기록", "개발이력 남겨", "마감", "이슈 기록", "프로젝트 페이지 만들어" 같은 요청에 적용한다. Notion 연결이 없으면 SESSION_LOG.md에 같은 내용을 누적해 기록을 잃지 않는다. 일반 작업 보고나 사소한 수정에는 호출하지 않는다.
---

# devlog

프로젝트 개발 이력을 일관된 포맷으로 Notion에 누적한다. 절차와 포맷은 여기에 두고, 프로젝트 지침 파일에는 트리거 한 줄만 둔다.

## 0. 사전 점검

1. **사용 여부 확인.** 이 프로젝트에서 Notion 기록을 쓰는지, 어느 부모 페이지에 쓰는지, 어떤 범위의 내용을 올리는지를 첫 기록 전에 사용자에게 한 번 확인한다. 이미 승인된 프로젝트는 다시 묻지 않는다.
2. **부모 페이지 찾기.** 아래 순서로 정한다. 값이 없으면 사용자에게 묻고 임의로 고르지 않는다.
   1. 이번 요청에서 사용자가 준 URL 또는 ID
   2. 프로젝트 `PROGRESS.md`의 `Notion 부모 페이지` 항목
3. **연결 확인.** `notion-search` 같은 Notion 도구를 호출할 수 있는지 본다.
   - 연결됨: 아래 1~4 절차.
   - 미연결 또는 실패: `references/fallback.md`로 전환한다. 허용된 경우 SESSION_LOG.md에 append하고, 실제 저장 결과를 확인한 뒤에만 기록했다고 알린다. 저장하지 못했거나 결과가 불명확하면 미저장 또는 저장 여부 미확인으로 보고한다. 기존 이력은 덮어쓰지 않는다.

Notion 기록이 실패하거나 승인되지 않아도 본 작업은 막지 않는다.

## 1. 트리거 판정

다음 중 하나일 때만 기록한다. 아니면 호출하지 않는다.

- 마일스톤 완료
- 세션 마감("마감", "종료")
- 중요 이슈: 에러 해결, 설계 변경, 의사결정

세션 마감 트리거에서는 Notion 기록과 함께 `PROGRESS.md` 최신본을 갱신한다. `PROGRESS.md`는 장기·다중 세션 프로젝트에서만 유지하고, 단순 작업에는 만들지 않는다.

## 2. 신규 프로젝트: 페이지 최초 생성

프로젝트 페이지가 아직 없을 때만 한다.

1. `notion-search`로 `[프로젝트명]`을 검색한다. 이미 있으면 새로 만들지 않고 그 페이지에 누적한다.
2. 없으면 `notion-create-pages`로 부모 페이지 아래에 만든다.
   - 제목: `[프로젝트명] - YYYY-MM-DD`
   - 초기 섹션 4개: `## 개요`(목적, 기술 스택, 경로) / `## 개발 이력` / `## 이슈 트래커` / `## 메모`
3. 반환된 페이지 URL을 `PROGRESS.md`의 `Notion 기록 URL` 항목에 적는다. 재시도 전에는 중복 페이지가 없는지 먼저 확인한다.

## 3. 이력 추가: 표준 포맷

기존 페이지를 `notion-fetch`로 연 뒤 `## 개발 이력` 섹션 끝에 `notion-update-page`로 아래 블록을 append한다. 기존 내용은 보존한다.

```
### [YYYY-MM-DD HH:MM] 작업 제목 (유형: 기능구현|디버깅|리팩토링|설계|이슈)
- 내용: [2~3줄 요약]
- 변경 파일: [핵심 파일과 변경 요점]
- 결과: 완료 | 진행 중 | 블로킹
- 다음 작업: [후속 태스크]
```

- 유형은 5종 중 하나. 시각은 사용자의 시간대 기준으로 쓴다.
- 요약은 2~3줄을 넘기지 않는다. 확인한 사실만 쓰고 미확인은 없음·완료로 바꾸지 않는다. 날짜·시각은 확인된 값만 쓰며, 시간대나 시각을 알 수 없으면 묻거나 미확인으로 둔다.
- Notion·로컬 파일 각각의 작성, 저장 확인, 동기화 상태를 구분한다. 초안이나 시도만으로 기록·동기화 완료를 주장하지 않는다.
- 비밀값(토큰, 비밀번호, 키), 개인정보, 고객사명, 내부 주소는 기록하지 않는다. 필요하면 마스킹하거나 일반화한다.

## 4. 이슈 트래커 (선택)

설계 변경과 블로킹 이슈는 `## 개발 이력` 기록과 별도로 `## 이슈 트래커`에도 한 줄 요약을 남긴다. 이슈 트래커를 DB로 운영 중이면 `notion-query-data-sources`로 중복을 확인한 뒤 추가한다.

## 동작 요약

- 신규: search로 중복 확인 → 없으면 create-pages → URL을 PROGRESS.md에 기록.
- 기존: fetch → 개발 이력에 표준 블록 append.
- 미연결·미승인: `references/fallback.md`.

## 5. 세션 핸드오프

긴 작업을 새 세션으로 넘길 때는 `references/handoff.md` 구조로 상태를 남긴다. 마지막 완료 단계, 진행 중 작업, 핵심 결정, 검증 상태, 열린 이슈, 다음 행동을 적고 Notion 또는 `SESSION_LOG.md`에 같은 내용을 둔다. 새 세션은 중간 작업을 재개하지 않고 다음 행동부터 시작한다.

## 특정 정보가 필요할 때

기관명, 고객명, 호스트명, 주소, 계정, 내부 식별자처럼 특정 대상을 가리키는 값이 필요하면 추측하거나 파일에 미리 적지 않는다. 필요한 항목을 모아 한 번에 질문하고, 받은 답은 이번 산출물과 세션에만 쓴다. 이 스킬의 파일과 저장소에는 되쓰지 않는다. 자격증명과 개인정보는 요청하지 않는다.