문서 수정 (Revise docs)
공식 명령어 파일 관리 플러그인은 revise 명령어를 제공하여 세션의 학습 내용을 루트 명령어 파일 끝에 덧붙입니다. 이 스킬이 존재하는 이유는 바로 그 동작을 대체하기 위함입니다. 계속 커지는 루트 파일은 끝까지 읽히지 않으며, 덧붙여진 학습 내용은 나중 세션이 필요로 하는 순간에 정작 필요한 사실인 경우가 드뭅니다. 이 스킬은 해당 플러그인의 유용한 절반(코드베이스에 대한 주장을 쓰기 전에 감사하는 과정)은 유지하고, 덧붙이는 절반은 라우팅으로 대체합니다. 도구 자체의 시스템-로컬 메모리 노트는 이미 세션이 학습한 내용과 명령어 파일이 이미 말하고 있는 내용을 건너뛰므로, 이 스킬은 공유 가능하고 버전 관리에 포함되는 절반(규칙은 해당 표면을 다루는 경로를 가진 규칙 파일로, 사건은 저장소 아카이브로)을 라우팅합니다.
기본 경로
- 이 세션이 만들어낸 것 중 보관할 가치가 있는 것의 이름을 정하세요: 수정 사항, 결정된 규칙, 버그와 그 수정, 측정된 결과, 두 접근 방식 사이의 결정.
- 그것을 규칙(rule) 또는 사건(incident) 으로 분류하세요.
- 규칙은 유사한 상황이 반복될 때마다 유효합니다. 한 번 명시하면 다음 리팩터링 후에도 여전히 참이어야 합니다.
- 사건은 특정 날짜, 이름, 또는 측정된 숫자가 있는 한 번 발생한 일입니다. 규칙이 존재하는 이유에 대한 증거일 뿐, 규칙 자체는 아닙니다.
- 규칙을 일치하는 규칙 파일로 라우팅하세요.
- 파일 이름만으로 검색하지 말고, 범위와 제목을 기준으로 기존 규칙 파일을 검색하세요. 학습 내용이 다루는 표면을 이미
paths:로 커버하는 파일을 여세요. - 하나가 커버한다면, 새 제목을 추가하거나 기존 항목에 내용을 통합하세요. 규칙 형태를 따르세요: 규칙 자체인 명령형 제목, 이유에 대한 한 가지 절, 이를 강제하는 대상을 명시하는
Anchor:줄, 아카이브 항목을 가리키는Receipts:줄, 그리고 파일이## Don't로 끝나도록 유지하세요. - 쓰기 전에 확인하세요.
Anchor:줄의 모든 토큰, 모든 경로, 모든 스크립트 이름이 지금 저장소에 실제로 존재하는지 확인하세요. 이것이 위 플러그인에서 가져온 감사 습관입니다: 확인하지 않은 주장은 절대 쓰지 마세요. - 아무것도 커버하지 않는다면, 그렇게 말하고 새 규칙 파일을 제안하거나 기존 파일의 범위를 넓히세요. 가깝다는 이유만으로 가장 가까운 파일에 내용을 떨어뜨리지 마세요.
- 파일 이름만으로 검색하지 말고, 범위와 제목을 기준으로 기존 규칙 파일을 검색하세요. 학습 내용이 다루는 표면을 이미
- 사건을 저장소의 아카이브 계층으로 라우팅하세요.
- 아카이브는 저장소가 날짜가 있는 증거 문서(핸드북 장, 설계 이력 파일, 사후 분석 로그)라고 부르는 것입니다. 날짜, 이름, 측정된 숫자를 한 줄짜리 교훈으로 제목을 붙여 항목이 파일 이름이 아닌 주장으로 읽히도록 기록하세요.
- 규칙 파일이 인용된 제목과 함께 항목을 가리키도록 하세요. 규칙 본문 내에서 사건의 세부 사항을 다시 설명하지 마세요. 규칙 속의 날짜나 숫자는 규칙의 옷을 입은 역사일 뿐입니다.
- 저장소에 아카이브가 아직 없다면, 그렇게 말하고 하나를 시작할 것을 제안하세요. 집이 없다는 이유로 사건을 규칙 파일이나 루트 파일에 넣지 마세요.
- 루트 명령어 파일은 절대 건드리지 마세요. 규칙 파일도 아카이브도 적합하지 않다면, 그 사실이 충분히 오래 지속되지 않는다는 신호이지, 루트 파일에 기본적으로 넣을 이유가 아닙니다. 그렇게 명확히 말하고 중단하세요.
- 저장하기 전에 수정 사항을 보여주세요. 제안하는 제목과 문단을 인쇄하거나, 기존 파일과의 차이점(diff)을 보여주고, 명확히 "그냥 변경하라"고 지시받지 않는 한 확인을 기다리세요.
일치 항목이 관리되는 하우스 규칙인 경우
이미 해당 주제를 다루는 파일이 벤더된 하우스 규칙(managed-file 헤더가 있고 .claude/rules/house/** 아래에 있음)이라면, 이 저장소에서 편집하지 마세요. 관리되는 파일에 대한 로컬 편집은 다음 /house-rules:sync 실행 시 자동으로 덮어씌워지며, 이러한 자동 손실은 바로 하우스 규칙이 방지하고자 하는 것입니다.
대신 상위 저장소에 변경을 제안하세요. 동일한 제목과 문단을 초안으로 작성하고, 이 저장소가 아닌 하우스 저장소에서 변경 사항을 열라고 말하세요. 만약 그 내용이 이 저장소에만 국한된 것이지 전체 함대(fleet) 규칙이 아니라면, 관리되는 파일을 포크(fork)하는 대신 house.json에 예외로 기록하세요. 두 경로 모두 관리되는 파일을 동기화 상태로 유지합니다. 제자리에서 편집하는 것은 그렇지 않습니다.
탈출구 (Escape hatches)
- 학습 내용이 기존 규칙과 모순됩니다. 그렇게 명확히 말하고, 기존 제목을 인용한 후, 쓰기 전에 어느 것이 우선인지 물어보세요. 한 규칙을 다른 규칙으로 조용히 덮어쓰지 마세요.
- 학습 내용이 규칙 형태를 갖추지 않은 저장소 특정의 일회성 내용입니다. 공급업체 버그에 대한 해결 방법, 한 번만 중요한 메모 등입니다. 미래 세션이 따라야 할 필요가 없는 내용으로 규칙 파일을 어지럽히는 대신 사건으로 아카이브에 라우팅하세요.
- 무언가가 규칙인지 사건인지 확실하지 않습니다. 아카이브 쪽으로 기울이세요. 잘못 아카이브된 규칙은 나중에 누군가가 승격시킬 수 있는 제목일 뿐입니다. 잘못 규칙으로 분류된 사건은 아무도 플래그를 지정하지 않는 낡은 산문이 됩니다.
- 저장소에 규칙 파일도 아카이브도 전혀 없습니다. 그렇게 명확히 말하고, 이 스킬 내에서 둘 중 하나를 새로 만들기보다는 중단하세요. 그것은 이 스킬의 역할이 아니라
/house-rules:bootstrap의 역할입니다.
하지 말아야 할 것 (Don't)
- 루트 명령어 파일에 추가하지 마세요. 그것은 공식 명령어 파일 플러그인의
revise명령어가 수행하는 동작이며, 이 스킬이 대신 존재하는 이유입니다. - 코드베이스에 대해 확인하지 않은 앵커가 있는 규칙 문장을 쓰지 마세요.
- 규칙 본문 내에서 사건의 날짜, 이름, 또는 숫자를 다시 진술하지 말고, 아카이브를 가리키세요.
- 벤더된 하우스 규칙 파일을 제자리에서 편집하지 마세요. 상위 저장소에 제안하거나 예외를 기록하세요.
- 상대방이 보지 않은 수정 사항을 저장하지 마세요. 단, 그들이 명확히 "그냥 하라"고 말한 경우는 예외입니다.
- 저장소에 규칙 파일이나 아카이브가 없을 때 이를 새로 만들지 마세요.