Project Notes

---
name: project-notes
description: 진행기록 폴더(notes)를 쓰는 저장소에서 세션을 시작하거나, 기록을 어디에 남길지 판단하거나, 커밋·push 를 할 때 사용한다. 현황판 읽기 → 작업자 확정 → 반입 스캔 순서와 문서별 역할 분담, 커밋 원칙을 정한다.
---

# 진행기록 방법론 - 세션 절차

이 저장소는 결과물만이 아니라 **거기 도달한 과정**을 기록한다. 현황판·ADR·아카이브를
3분리해 각 문서가 담는 것을 섞지 않는 게 이 방법론의 핵심이다.

설정값은 `<repo>/.claude/girok.json` 에서 읽는다. 아래에서 `{notesDir}` `{id}`
`{remote}` 는 그 값으로 치환한다.

## 세션 시작 절차

훅이 자동으로 수행한다. 플러그인이 없어도 훅 등록은 저장소의 `.claude/settings.json`
에 커밋돼 있어 그대로 돈다. 훅이 붙지 않는 환경 - 폴더 신뢰 미승인, Python 없음, Claude
Code 가 아닌 에이전트 - 에서는 사람이 이 순서를 따른다.

1. **현황판을 먼저 읽는다** - `{notesDir}/docs/PROGRESS.md`. 지금 상태·활성 위험·열린
   질문을 파악한다. 작업과 관련된 결정은 `docs/decisions/README.md` 인덱스에서 해당
   ADR만 골라 읽는다(전부 읽지 않는다).
2. **작업자를 확정한다** - `git config user.email` 을 설정의 `workers` 매핑과 대조한다.
   매핑에 없거나 후보가 둘 이상이면 **그때만** 사람에게 묻는다. 병행 작업 중이면
   `parallel-docs` 스킬의 확인 절차가 우선한다.
3. **반입 스캔** - `git fetch {remote}` 후 다른 작업자의 새 커밋·스탬프 갱신 여부를 본다.
   상세는 `parallel-docs` 스킬.
4. `modules.safetyGate` 가 켜져 있으면 `SAFETY_GATE.md` 의 OPEN 개수를 확인한다.

## 무엇을 기록하는가

방향 결정, 시행착오, 사용자 피드백으로 방향이 바뀐 지점 - 굵직한 흐름이 생길 때마다
기록한다. **하이퍼파라미터급 사소한 수정은 기록하지 않는다.** 실제로 방향을 바꾼
시행착오와 결정만 남긴다.

방향 결정은 ADR 로 남기고(→ `writing-adr`), 현황판에는 일자별 로그 한 줄로 **ID만
인용**한다. 결정 내용을 다른 문서에 재서술하지 않는다 - 판단이 뒤집힐 때 고칠 곳이
파일 하나로 좁혀지게 하기 위함이다.

## 문서별 역할 - 섞지 않는다

| 문서 | 담는 것 |
|---|---|
| `docs/PROGRESS.md` | 현황판 - 상태 스냅샷·활성 위험·열린 질문·얇은 일자별 로그 |
| `docs/decisions/` | 결정 기록(ADR) - 결정 1건 = 파일 1개 + `README.md` 인덱스 |
| `docs/archive/` | 완결된 서사 원문 스냅샷 - **갱신하지 않음**, 이동 시점 그대로 |
| `docs/AI_USAGE.md` | AI 를 어떻게 썼는지 - 세션 타임라인·사용 모델·시행착오 |
| `docs/SAFETY_GATE.md` | (옵션) 안전 게이트 항목·확인자·배포 기록 |

## AI 사용 기록

새 도구·CLI 를 실제 작업에 썼거나 시행착오가 생기면 `AI_USAGE.md` 에 반영한다 -
**"시도했다가 되돌린 것" 절을 채우는 게 핵심**이다.

단 **스킬·플러그인 목록은 적지 않는다.** 머신마다 다르고 효과를 잰 적이 없어서, 적으면
"켜져 있었다"가 "효과 있었다"로 읽힌다. 절차가 의존하는 것(없으면 문서에 적힌 절차가
안 돌아가는 것)만 도구로 적는다.

## 판단을 뒤집었을 때

인용된 곳을 전부 찾아 고친다. `grep -rn "ADR-<id>"` 로 인용처를 찾고, 관련 ADR 상태를
`superseded-by-<새 ID>` 로 바꾼 뒤 **새 ADR 에** 왜 틀렸는지 적는다(기존 ADR 본문은
고치지 않는다).

## 경로 표기

로컬 절대경로를 문서에 새로 기록하지 않는다 - 머신마다 달라진다. 저장소를 가리킬 땐
저장소 이름만 쓴다. 설비 설정값처럼 그 값 자체가 사실인 절대경로는 예외다.

진행기록 폴더는 **문서 전용**이다. 코드·바이너리를 이 폴더 아래 두지 않는다
(폴더 `.gitignore` 로 막는다).

## 대시 표기

대시는 **키보드의 하이픈(`-`, U+002D)만** 쓴다. em dash(U+2014)·en dash(U+2013)는 쓰지
않는다. 문서만이 아니라 코드·주석·문자열·커밋 메시지·PR 본문까지 **어떤 작업이든** 같다.
기존 파일에서 em dash·en dash 를 보면 손대는 김에 하이픈으로 바꾼다.
문서 검사기(`check_docs.py`)가 남은 것을 경고로 알린다.

목차를 손으로 쓸 때 주의: 공백으로 감싼 하이픈(`제목 - 부제`)은 GitHub 앵커에서 지워지지
않아 `#제목---부제` 가 된다.

## 커밋과 push

1. **세션 단위로 커밋하지 않는다.** 의미 있는 변경(새 ADR, 현황판 구조 변경, 문서 체계
   개편)이 생긴 시점마다 커밋한다. 오타 수정 같은 사소한 변경은 다음 의미 있는 커밋에
   묶는다.
2. 커밋 전 `git status` 로 변경분을 확인하고 의도한 파일만 `git add` 한다
   (`git add -A` 남발 금지).
3. 커밋 메시지는 한 줄 요약 + 필요하면 본문. 무엇을 바꿨는지보다 **왜** 바꿨는지 위주로.
4. **커밋을 만들면 그 자리에서 즉시 자기 브랜치를 push 한다** - 커밋과 push 는 한 묶음으로
   취급하고 밀어두지 않는다. push 실패(오프라인·인증)면 즉시 사용자에게 알리고, 세션
   마무리 때 미push 커밋이 없는지 한 번 더 확인한다.
5. **force-push 금지.** 변경 이력 자체가 결정 기록이라 되돌리기 어렵다. 이력 정리가
   필요하면 트리 불변 커밋(`-s ours` 조상 연결 등)으로 해결한다.
6. **참고 저장소(`readOnlyRepos`)에는 수정·커밋·push 를 만들지 않는다.** 코드 대조·이식
   출처로만 쓴다. 고칠 것이 발견되면 작업 저장소 쪽에 반영하고 ADR·게이트로 기록한다.

## 세션 마무리

현황판 맨 위 "일자별 작업 로그"에 오늘 날짜 행을 추가한다(같은 날짜면 그 행을 고쳐 씀).
**되돌린 시행착오 말고 그날 최종적으로 남은 결과만** 적는다. 같은 시점에 "상태 요약" 표도
훑어 바뀐 행을 고친다. 상세는 `progress-board` 스킬.