note-save

노트 저장 계약

설정: 노트 폴더는 NOTES_DIR 환경변수(기본 ~/notes). 아래 $NOTES는 그 경로를 뜻한다. 폴더 이름·분류는 예시다. 본인 체계로 바꾸되, 5단계 계약 자체는 유지하라 — 계약이 이 스킬의 존재 이유다.

$NOTES는 git 버전 관리되는 llms.txt 인덱스 기반 지식기반이다. 이 스킬은 저장의 5단계 계약을 강제한다. 계약이 지켜져야 다음 세션의 에이전트가 탐색 없이 문서를 찾고(주소체계), 신선도를 판단한다(출처 관리).

[!important] 왜 "부탁"이 아니라 "계약"인가 "저장할 때 인덱스도 갱신해줘"라고 부탁하면 잊힙니다. 그래서 저장하는 통로를 하나로 만들고, 그 통로에 인덱스 등재를 박아둡니다. 부탁은 잊히지만 계약은 안 잊힙니다. 이게 레벨 2(문서)와 레벨 3(시스템 강제)의 차이입니다.

1단계 — 폴더·파일명 결정

내용	폴더	파일명 규칙
재사용 코드 모듈	11_Modules	[분류]_[기능]_[언어].md (날짜 없음)
조사/학습 기록	12_Research	[주제]_[키워드]_[YYMMDD].md
에러 해결 기록	13_Troubleshooting	[기술스택]_[에러키워드]_[YYMMDD].md
구현 명세서	14_Specs	[프로젝트]_[YYMMDD].md
주간 리뷰	15_Reviews	weekly_[YYYY-Wnn]_[YYMMDD].md

• 저장 전 해당 폴더의 llms.txt에서 같은 주제의 기존 문서를 확인하라 — 있으면 새 파일을 만들지 말고 기존 파일을 갱신하고 updated:를 바꾼다. 중복 문서가 최악이다.
• macOS에서 한글 파일명은 NFC 정규화 필수 (자모 분해 주의 — Write 도구는 NFC로 쓰지만 mv/cp로 만들 땐 확인).

2단계 — frontmatter 주입 (신규 문서 필수)

---
created: YYYY-MM-DD
updated: YYYY-MM-DD          # 내용 갱신 시마다 변경
source: <출처>               # 세션 주제·커밋 해시·URL·프로젝트 경로 등 이 지식이 나온 곳
related: ["[[문서명]]"]      # 관련 문서 위키링크 (없으면 생략)
---

• winner 규칙: 같은 주제 문서가 충돌하면 updated가 최신이고 llms.txt에 등재된 쪽이 정본이다. 패자는 내용을 병합한 뒤 휴지통으로 이동한다(삭제 금지).
• frontmatter 없는 구작을 갱신할 때는 이 기회에 추가한다. 구작 일괄 소급은 하지 않는다 (한 번에 다 고치면 뭐가 바뀌었는지 알 수 없다).

⚠️ frontmatter 값에 콜론(:)이 들어가면 큰따옴표로 감싸야 YAML 파싱이 깨지지 않는다.

3단계 — 본문 작성

해당 폴더 llms.txt의 "문서 구조" 섹션 템플릿을 따른다 (폴더마다 다르다 — 반드시 읽고 따를 것).

공통 원칙: 미래의 에이전트가 llms.txt 요약만 보고 열람 여부를 결정한다 → 제목과 첫 단락에 결론을 담아라.

4단계 — llms.txt 등재 (★ 이 단계가 빠지면 저장 안 한 것과 같다)

• 해당 폴더 llms.txt의 목록 테이블에 한 줄 추가: 파일명 | 요약 | (폴더별 추가 열) | 날짜
• 요약은 3~5줄 분량으로 밀도 있게 — 핵심 결론·수치·관련 문서 위키링크 포함
• "~에 대한 문서" 같은 동어반복 금지. 결론 자체를 적어라

5단계 — 검증·커밋

python3 ~/.claude/scripts/note-lint.py     # 미등재·dangling·명명·frontmatter 위반 0건 확인
cd "$NOTES" && git add -A && git commit -m "docs: <무엇을 왜>" && git push
python3 ~/.claude/scripts/note-search.py index   # 검색 색인 증분 갱신 (신규 문서 즉시 검색 가능)