wiki-smith — 레포지토리의 .wiki/ 유지하기
위키는 에이전트를 위해 작성된 레포지토리의 메모리입니다. 에이전트는 여기서 규칙을 찾고 다시 묻지 않습니다. 일기는 일어난 일을 기록하고, 주제 페이지는 지금 유효한 규칙을 담습니다. 일기에만 존재하는 교훈은 사라집니다. wiki-smith는 세션이 필요로 하는 것이 둘 중 무엇인지 결정하고, 이 위키 자체의 규칙이 말하는 방식으로 작성한 후 검증합니다.
전체 방법론 (파일 유형, 노트 형식, 수집, 링킹, 날짜, 커밋): references/method.md. 설정 키: references/config.md. 크레딧: ATTRIBUTION.md. 변경 사항: CHANGELOG.md. 자신의 메모리: .wiki/.
아래 <skill>은 이 스킬의 폴더입니다 (예: ~/.claude/skills/wiki-smith). 모든 스크립트는 -w <wiki 디렉토리> (기본값 ./.wiki)와 -c <설정> (기본값 <wiki>/wiki.config)을 받습니다.
0단계 — 위키와 그 규칙 찾기
- 위키는 레포지토리 루트의
.wiki/입니다. 만약 없다면, 그렇게 말하고 templates/에서 생성할 것을 제안하십시오 (wiki.config.example부터); 요청받지 않고 절대 생성하지 마십시오. .wiki/wiki.config가 있으면 읽으십시오 (이름: 일기 폴더, 받은 편지함, 인덱스, 푸터 레이블, 날짜 키, 메인 브랜치). 기본값은 일반적인 영어입니다:journal/,inbox.md,index.md,Map:,## History,created/updated.- 위키 자체의 규칙이 우선합니다. 레포지토리에 유지보수 방법에 대한 페이지 (
rg -n -i '유지보수|관리' .wiki -l) 또는 위키에 관한AGENTS.md규칙이 있다면, 해당 섹션을 읽고 이 스킬과 다른 부분을 따르십시오. - 사용자가 "wiki update"를 요청했고 위키(보통 인덱스)가 먼저 확인하라고 한다면, 1단계와 2단계를 계획으로만 수행하십시오: 페이지당 한 줄씩 어떤 변경사항이 있는지, 새 노트의 제목을 제시한 후 "적용할까요?"라고 묻고 승인 후에만 편집하십시오. 그렇지 않으면 바로 실행합니다.
1단계 — 발생한 일을 보고 라우팅하기
세션(그리고 git diff, git log로 수행된 작업)을 읽으십시오. 해당하는 모든 행을 선택하고, 다른 것은 선택하지 마십시오:
| 세션의 내용 | 수행할 작업 |
|---|---|
| 결정, 인도, 방향 변경, 인시던트 또는 연구 | 일일 노트: scripts/note.sh -b "변경된 내용을 설명하는 제목" 와 함께 단락을 파이프로 전달합니다. 그런 다음 받은 편지함에 해당 날짜의 줄을 추가합니다. |
| 오늘 이후로도 유효한 규칙, 교훈 또는 사실 | 주제 페이지도 수정: 지금 유효한 규칙, 내역 없음 (내역은 노트와 페이지의 History 섹션에 유지됩니다). 페이지가 이전에 말한 내용을 수정하십시오; "예전에는 이랬다" 식으로 쌓지 마십시오. |
| 여러 측면을 가진 새로운 주제 (다시 나타날 것이고, 하나의 페이지가 여러 종류를 혼합하게 될 경우) | 콘텐츠 맵 moc-<주제>.md 와 페이지들 <주제>-<측면>.md (치트시트, 설치, 통합, 현재 도구와의 비교...)을 만드십시오. 아래 "새 주제"를 참조하십시오. |
| 기록할 가치가 없는 것 (중간 단계만 있거나, 커밋이 이미 말하고 있는 경우) | 한 줄로 말하고 아무것도 만들지 마십시오. 일기를 채우면 읽을 수 없게 됩니다. |
일기를 위해 항상 새로운 노트만 생성됩니다; 다른 에이전트의 노트를 절대 다시 쓰지 마십시오.
2단계 — 작성
일일 노트. scripts/note.sh "<제목>"은 <DIARY_DIR>/<오늘>/<HHMM>-<슬러그>.md 파일을 UTC 기준으로 생성하고 경로를 출력합니다 (슬러그 규칙과 충돌 시 -2 처리는 스크립트에 있습니다). Stdin은 -b와 함께만 읽습니다: 에이전트 셸과 CI는 stdin을 영원히 열어두므로, -b 없이는 스크립트가 절대 기다리지 않습니다. 본문을 파이프로 전달하십시오: printf '%s\n' "<단락>" | scripts/note.sh -b "<제목>"; -b는 제목과 본문 사이에 정확히 하나의 빈 줄을 넣습니다. -b 없이 파일은 제목 줄만 있습니다; 나중에 단락을 추가하려면 빈 줄로 시작하십시오: printf '\n%s\n' "<단락>" >> "$path". 본문은 잘 작성된 하나의 단락입니다: 무슨 일이 있었는지, 왜 중요한지, 증거가 어디에 있는지 (커밋, PR, 이슈), 주제 페이지에 대한 링크가 포함됩니다. 링크는 일일 폴더에 대해 상대적입니다 (../../page.md). 템플릿: templates/note.md.
그날의 첫 번째 노트: scripts/day-index.sh가 그날의 인덱스를 생성합니다; 그런 다음 받은 편지함의 "최근 날짜" 맨 위에 해당 날짜를 추가합니다. 노트가 레포지토리 작동 방식을 변경한다면, 받은 편지함의 하이라이트에 한 줄도 추가하십시오. 받은 편지함은 노트를 보관하지 않습니다.
주제 페이지 (수집). 찾으십시오 (rg -n -i '<단어>' .wiki); 존재하지 않고 주제가 다시 나타날 것 같으면 생성하십시오 (템플릿: templates/page.md); 작다면 인접한 페이지의 섹션에 넣으십시오. 지금 유효한 규칙을 작성하십시오. 변경으로 인해 페이지의 주장이 바뀌면 History 섹션 맨 위에 한 줄을 추가하십시오. 노트는 페이지를 링크합니다.
새 주제.
- 먼저 페이지들을 작성하십시오. 각 측면별로 하나씩, 첫 문장부터 독립적으로 작성하십시오. 일반적인 측면: 치트시트 (시작하기 좋은 것: 주소, 명령, 단축키), 설치, 통합, 현재 사용 중인 도구와의 비교.
moc-<주제>.md를 생성하십시오 (templates/moc.md): 시작 단락, "페이지들" (각각 한 줄씩, 치트시트 우선), "먼저 알아야 할 것" (문제를 일으키는 몇 가지 규칙).- 모든 페이지에 푸터를 제공하십시오 (
맵: [moc-<주제>](moc-<주제>.md) · 관련: ...), 맵과 각 페이지를 인덱스에 추가하고, 맵을 다른 맵 중 하나 이상에서 링크하십시오. - 일기의 노트는 무엇이 생성되었는지 말하고 맵을 링크합니다.
3단계 — 마무리 (항상, 이 순서대로)
scripts/dates.sh— git에서created/updated프론트매터를 업데이트합니다. 멱등적입니다.scripts/day-index.sh— 일일 인덱스를 재생성합니다. 수동으로 편집하지 마십시오.python3 -I scripts/lint.py— 출력되는 모든file:line: type: message를 종료 코드 0이 될 때까지 수정하십시오 (종료 코드 2는 문제를 의미합니다). 빨간 린트를 푸시하지 마십시오.- 경로별로 자신의 파일만 커밋하고, 절대
git add -A를 사용하지 마십시오:scripts/sync.sh -m "wiki: <내용>" <경로>.... 체크아웃이<main>에 있고, 최신이며, 자신의 경로 외부에 변경 사항이 없으면 제자리에서 커밋합니다; 그렇지 않으면origin/<main>에서 새로운git worktree로 자신의 경로를 가져갑니다. 두 경우 모두 커밋할 내용을 정확히 린트하고 빨간 린트를 거부합니다 (종료 코드 1, 체크아웃 변경 없음, 가져간 작업 트리 제거). 가져갈 때 생성된 일일 인덱스는 절대 복사되지 않습니다: 작업 트리에서 재생성되므로 커밋에 포함된 노트만 나열합니다. 메시지에 레포지토리 또는 호스트가 요구하는 기여자 표시 줄을 추가하십시오.- 다른 세션에서도 편집했을 수 있는 공유 파일 (인덱스, 받은 편지함): 가져가기에 전달하지 마십시오.
scripts/sync.sh -W는origin/<main>에서 새 작업 트리를 인쇄합니다; 그곳에서 편집하고 (위키는 동일한 상대 경로에 있습니다),dates.sh,day-index.sh,lint.py를 실행한 다음 해당 작업 트리 내에서sync.sh -m ... [-p] <경로>를 실행하십시오. 거기서 커밋하고,-p를 사용하면 리베이스, 푸시, 메인 체크아웃을 가능한 경우 fast-forward하고, 작업 트리를 제거합니다. 다른 세션의 줄(예: 체크아웃에만 있는 페이지 링크)을 포함하는 가져가기는 린트에 실패하고 아무것도 커밋되기 전에 중단됩니다; 그 실패가-W를 사용하라는 신호입니다.
- 다른 세션에서도 편집했을 수 있는 공유 파일 (인덱스, 받은 편지함): 가져가기에 전달하지 마십시오.
- 사용자가 동기화를 요청한 경우에만 푸시하십시오: 동일한 호출에
-p를 추가하십시오 (fetch, rebase,push HEAD:<main>, 체크아웃 fast-forward, 작업 트리 제거). 절대 강제 푸시하지 말고, 다른 사람의 수정된 파일을 건드리지 마십시오: 푸시한 내용과 다르고 다른 세션의 편집 내용을 담을 수 있는 파일(인덱스, 받은 편지함)은 그대로 둡니다. 체크아웃을 fast-forward할 수 없는 경우 (로컬<main>이 분기되었거나, 로컬 편집 내용이 겹치는 경우) 그렇게 말하고 여전히 종료 코드 0으로 종료합니다. 푸시가 작동했기 때문입니다. 요청받은 경우에만 PR을 여십시오.
같은 세션에서 작성한 내용을 요청받지 않고 커밋하십시오; 게시는 사용자의 결정입니다.
위키 조회하기
rg -n -i '<키워드>' .wiki (또는 인덱스 훑어보기), 그런 다음 일치하는 페이지 또는 섹션만 읽고, 전체 위키를 읽지 마십시오. 무슨 일이 있었는지에 대해서는: 받은 편지함 (짧게), 그런 다음 중요한 날짜만; 하루 = 해당 인덱스와 나열된 노트들. 레포지토리에 명세가 있다면, 시스템이 약속하는 바를 말합니다: rg -n -i '<키워드>' <명세 디렉토리>.
함정
- 일기는 페이지가 아닙니다. 노트에만 작성된 규칙은 사라집니다; 같은 세션에서 주제 페이지로 수집하십시오.
- 내역 없는 규칙. "카드를 만들기 전에 기존 카드를 검색하세요"이지 "예전에는 카드를 중복해서 만들었습니다"가 아닙니다. 이야기는 노트에 남습니다.
- 파일당 하나의 노트. 여러 에이전트가 같은 날에 씁니다; 그들은 절대 같은 파일을 편집해서는 안 됩니다. 일일 인덱스는 생성되며, 충돌은
day-index.sh를 다시 실행하여 해결됩니다. - 세션 간 공유 파일. 일일 인덱스,
index.md및 받은 편지함은 하나의 체크아웃에서 모든 세션의 커밋되지 않은 편집 내용을 보유합니다.sync.sh는 일일 인덱스를 절대 가져가지 않고 (작업 트리에서 재생성) 커밋 전에 린트하지만, 수동으로 편집된index.md또는 받은 편지함의 어떤 청크가 당신의 것인지 알 수 없습니다: 가져가기는 전체 diff를 가져갑니다. 다른 세션이 파일을 건드렸을 수 있는 경우sync.sh -W를 사용하고 작업 트리에서 편집하십시오. 린트를 깨지 않는 외부 줄은 여전히 가져갑니다; 그것이 가져가기의 문서화된 한계입니다. - Stdin에서 절대 기다리지 마십시오.
note.sh는-b와 함께만 본문을 읽습니다; 에이전트 셸에서 맨 읽기는 영원히 차단됩니다. 추가하는 모든 스크립트에도 동일하게 적용됩니다. - 일시적인 것을 기록하지 마십시오: 한 번 실패했다가 재시도에서 성공한 명령, 환경 결함, 일회성 작업. 주제 페이지에 작동하는 수정 사항을 기록하고, "X가 고장 났다"는 절대 기록하지 마십시오 (원인이 사라진 후 거부로 굳어집니다).
- 링크: 상대 링크, 섹션당 첫 번째 언급에만 사용하십시오; 앵커는 GitHub의 제목 슬러그입니다 (소문자, 구두점 없음, 악센트 유지, 공백은 하이픈). 제목 이름을 바꾸면 앵커가 깨집니다; 린트가 이를 알려줍니다. 린트가 읽지 않도록 백틱 안에 링크 예제를 넣으십시오.
- 페이지 이름 바꾸기 또는 삭제:
rg -l '이전-이름' .wiki를 실행하고 앵커를 포함한 모든 링크를 수정하십시오; 콘텐츠가 이동한 후에만 삭제하십시오. - 페이지 크기: 약 150줄을 넘거나, 규칙, 절차, 참조 및 내역이 혼합되면 종류별로 분할하십시오.
- 개인 데이터는 밖에 두십시오. 위키 페이지는 커밋됩니다; 비밀, 토큰 및 개인 데이터를 밖에 두고, 비밀이 있는 곳을 참조하십시오.
- 린트 한계: 페이지 간 모순이나 오래된 주장을 잡아내지 못합니다; 그것은 시간이 허락할 때 에이전트의 검토에 맡깁니다.
day-index.sh한계: 수동으로 작성된 이전 형식의 노트가 있는 날짜 파일은 오류(file:line)이며, 마이그레이션되지 않습니다;note.sh를 사용하여 각 노트를 자체 파일로 이동한 후 다시 실행하십시오.
4단계 — 자신의 위키 유지하기
이번 실행이 wiki-smith 자체 실행에 대해 무언가를 가르쳐 주었다면 (라우팅 실수, 스크립트 특이점), .wiki/lessons.md에 한 줄을 추가하십시오: - YYYY-MM-DD — <규칙 + 이유>. 소스 클론 (biliboss/wiki-smith)을 편집하고 재설치하십시오 (npx skills add biliboss/wiki-smith -g --copy -a claude-code -y), 설치된 복사본이 아니라, 재설치 시 덮어쓰여집니다. 설계 결정은 .wiki/design.md에 기록합니다.