jimweller/documenter-plugin

프로젝트 문서 업데이트

두 가지 책임:

1. CLAUDE.md — 간결한 프로젝트 개요 (항상 로드됨)
2. .llmdocs/ — 상세 개념별 문서 (필요 시 로드됨). 모든 파일은 지속적인 설계 문서입니다.

---

1. CLAUDE.md — 지도

범위

프로젝트의 모든 CLAUDE.md 및 .llmdocs/ 디렉토리를 찾아 각각 업데이트합니다. 하위 폴더 계층, 범위 및 경계 컨텍스트에 주의하세요. 다른 계층의 문서 간에 개념이 유출되지 않도록 하세요. 각 CLAUDE.md 및 .llmdocs/는 자신의 디렉토리 수준과 그 아래를 다루며, 상위 컨텍스트는 절대 다루지 않습니다.

사용자가 특정 지침이나 집중 영역을 제공한 경우, 업데이트할 문서와 강조할 내용을 결정할 때 해당 컨텍스트를 적용하세요.

컨텍스트 수집

git을 직접 실행하지 마세요. 이 플러그인과 함께 제공되는 기본 스크립트가 이 스킬이 git에서 필요로 하는 모든 것을 처리합니다. 각 명령은 리포지토리 루트에서 실행하고 스크립트의 전체 경로를 매번 작성하세요. 셸 변수는 명령 간에 유지되지 않기 때문입니다.

계획부터 시작합니다. 계획은 모든 CLAUDE.md와 해당 .llmdocs/(아직 존재하지 않는 필수 파일 포함)를 찾고, 각 문서의 기준을 확인하고, 기준 이후 변경된 사항을 나열하고, 각 문서로 수행할 작업을 알려줍니다. 사용자 지침이 집중할 디렉토리 이름을 지정하는 경우 llmdocs 뒤에 전달하세요. 그렇지 않으면 아무것도 전달하지 마세요.

bash "${CLAUDE_SKILL_DIR}/../../scripts/doc-baseline.sh" plan llmdocs [<focus-dir>...]

계획은 작업당 하나의 블록을 출력합니다.

• ## update는 기준, 범위 및 해당 기준을 공유하는 문서를 지정한 다음 해당 기준 이후의 커밋, diff stat 및 상태를 나열합니다. 이 문서들을 최신 상태로 업데이트하세요. 변경 사항의 영향을 받지 않는 문서는 내용을 유지합니다.
• ## new는 현재 코드에서 작성할 문서를 나열합니다. 히스토리가 필요하지 않습니다.
• ## unchanged 및 ## outside the focus는 문서를 그대로 두도록 나열합니다.

head none은 리포지토리에 커밋이 없음을 의미합니다. 모든 문서가 새 문서입니다.

업데이트 블록의 경우 해당 stat의 파일 수를 셉니다. 20개가 넘으면 전체 diff를 건너뛰고 변경된 파일을 직접 읽으세요. 20개 이하이면 diff를 읽으세요. ??로 표시된 추적되지 않은 파일은 diff에 나타나지 않으므로 어느 쪽이든 직접 읽으세요. 범위는 블록의 범위 또는 단일 파일이 될 수 있습니다. git pathspec이기 때문입니다.

bash "${CLAUDE_SKILL_DIR}/../../scripts/doc-baseline.sh" diff <sha> <scope>

그런 다음, 업데이트하거나 작성할 문서가 있는 각 CLAUDE.md/.llmdocs/ 쌍에 대해:

1. 현재 CLAUDE.md 및 .llmdocs/의 모든 파일 읽기 (존재하는 경우)
2. 해당 디렉토리 수준 및 그 아래의 코드베이스 탐색
3. 관련 결정, 변경 사항 또는 교훈에 대한 대화 히스토리 검토
4. 변경 사항과 대화 컨텍스트를 사용하여 변경된 내용을 식별합니다. llmdocs는 현재 상태 명세서이며, 변경 로그, 결정 로그, 히스토리 레코드가 아닙니다. 히스토리 정보나 내린 선택을 절대 기록하지 말고, llmdocs를 작성하는 시점의 명세서만 기록하세요.

CLAUDE.md 작성/업데이트

목표: 500줄 미만. 모든 줄은 그 자리를 정당화해야 합니다.

# <이름>

<이 디렉토리/컴포넌트의 목적 1-2줄>

## 스택

<항목 목록: 언어, 프레임워크, 이 수준에 관련된 주요 의존성>

## 레이아웃

<이 수준의 주요 디렉토리와 그 내용>

## 명령어

<빌드, 테스트, 린트, 배포 — 명령어만>

## 컨벤션

<스타일, 명명, 패턴 — 실수를 방지하는 것만>

## 주요 개념

<Claude가 이 수준에서 알아야 할 도메인 용어, 비즈니스 로직>

## LLM 문서

`.llmdocs/`의 상세 문서:

- @.llmdocs/architecture.md — <1줄 설명>
- @.llmdocs/data-model.md — <1줄 설명>

CLAUDE.md 규칙

• 장황한 설명 금지 — Claude가 추론합니다.
• .llmdocs/ 내용 중복 금지 — 짧은 설명으로 참조만 하세요.
• ## LLM 문서 섹션은 모든 .llmdocs/ 파일을 각각 1줄 설명과 함께 반드시 나열해야 합니다.
• ## 문서 아래에 .llmdocs/ 파일을 나열하는 CLAUDE.md는 현재 제목보다 이전 버전입니다. 파일을 업데이트할 때마다 해당 제목을 ## LLM 문서로 변경하세요.
• 기존 사용자 정의 지침(git 워크플로우, 환경 변수 등)을 유지하세요.
• 코드가 내용과 모순되는 경우에만 내용을 제거하고, 요약에 각 제거 항목을 명명하세요.
• 코드가 함수, 플래그 또는 모듈을 삭제하는 경우, 이 수준의 모든 문서에서 해당 이름을 grep으로 검색한 다음, 각 적중 항목과 각 문서의 목적 줄을 다시 읽어 동일한 항목에 대한 일반 언어 설명을 찾으세요. 하나의 문서에서 이름을 제거하는 것만으로는 충분하지 않습니다.

grep -rn '<삭제된 이름>' <dir>/CLAUDE.md <dir>/.llmdocs

• 작성하거나 편집하는 텍스트에 마커 줄을 절대 포함하지 마세요. finish는 작성 후에 추가합니다. 이미 마커 줄로 끝나는 문서를 편집할 때는 해당 줄을 그대로 두세요.
• 문서를 항상 로드해야 하는 경우 @.llmdocs/filename.md 임포트를 사용하세요.

---

2. .llmdocs/ — 영역

프로세스

필수 7개를 넘는 개념 파일은 자유롭게 추가할 수 있으며, 계획은 이를 절대 명명하지 않습니다. finish는 실행 중 생성된 이 수준의 다른 모든 문서와 함께 어쨌든 스탬프를 찍습니다.

1. 평가: 계획의 업데이트 블록을 사용하여 영향을 받는 문서를 식별합니다.
2. 식별: 영향을 받는 기존 문서를 확인하거나 새 문서가 필요한지 결정합니다.
3. CLAUDE.md 업데이트: ## LLM 문서 섹션에 새 문서 파일이 나열되도록 합니다.

문서 업데이트가 필요할 정도로 변경된 것이 없으면 그렇게 말하고 진행하세요.

위치

CLAUDE.md의 ## LLM 문서 제목 아래 첫 번째 임포트가 명명한 경로를 사용하거나, 그보다 이전 CLAUDE.md의 ## 문서 아래 첫 번째 임포트가 명명한 경로를 사용하세요. 그렇지 않으면 대상 디렉토리 수준의 .llmdocs/를 기본값으로 사용하세요. CLAUDE.md와 .llmdocs/는 프로젝트의 모든 디렉토리 수준에 존재할 수 있습니다.

구조

평면, 개념당 1개 파일. 처음 7개 파일은 필수이며 항상 존재해야 합니다. testing.md는 프로젝트에 테스트 스위트가 있을 때 생성되고, 없을 때는 생략됩니다. 필요에 따라 추가 개념 파일이 생성됩니다.

.llmdocs/
  architecture.md    # 컴포넌트, 상호작용, 데이터 흐름 (필수)
  api.md             # 엔드포인트, 요청/응답, 인증, 권한 부여 (필수)
  data-model.md      # 스키마, 모델, 관계 (필수)
  deployment.md      # 배포 프로세스, 환경 (필수)
  ops.md             # 런북, 유지보수, 문제 해결 (필수)
  observability.md   # 로그, 메트릭, 트레이스, 상태 확인, 대시보드, 알림 (필수)
  security.md        # 신뢰 경계, 비밀 처리, 인증/권한 부여, 위협 모델 (필수)
  testing.md         # 테스트 레이아웃, 러너, 픽스처, 스위트 실행 방법 (프로젝트에 테스트가 있을 때)
  <concept>.md       # 필요에 따라 도메인별

문서 파일 형식

# <개념>

<1줄 목적>

## <섹션>

<내용: 헤더, 표, 코드 블록 — 산문 단락 없음>

.llmdocs/ 규칙

• 파일당 최대 500줄 — 더 크면 분할하세요.
• 유용한 경우 파일 경로와 줄 참조를 포함하세요 (src/auth/login.ts:42).
• 기존 문서를 점진적으로 업데이트하고, 처음부터 다시 작성하지 마세요.
• 문서가 정확하고 최근 변경 사항의 영향을 받지 않으면 내용을 그대로 두세요. finish는 여전히 마커를 업데이트합니다.
• 정확성이 범위보다 우선: 코드에서 검증 가능한 것만 문서화하세요.
• observability.md는 시스템이 내보내는 신호를 보유하고, ops.md는 운영자가 수행하는 작업을 보유합니다. 상태 엔드포인트, 로그 형식 또는 알림은 observability.md에 속합니다. 메트릭이나 트레이스가 없는 프로젝트라도 stdout, stderr 및 종료 코드를 여기에 문서화하세요.
• 작성하거나 편집하는 텍스트에 마커 줄을 절대 포함하지 마세요. finish는 작성 후에 추가합니다. 여기서 함정은 사용자가 생성하는 개념 파일입니다. 방금 읽은 모든 형제 파일이 마커 줄로 끝나기 때문입니다. 해당 줄을 복사하면 문서가 본 적 없는 커밋에 대해 확인되었다는 오래된 SHA를 작성하게 됩니다. 새 파일은 마지막 내용 줄에서 끝내고 finish가 마커를 추가하도록 하세요.

---

3. 완료

매번 finish를 실행하세요. 아무것도 작성하지 않은 실행도 포함합니다. plan은 계획 파일을 남겨두고 finish만 제거하므로, finish를 건너뛰면 다음 실행이 걸려 넘어질 상태가 남습니다.

bash "${CLAUDE_SKILL_DIR}/../../scripts/doc-baseline.sh" finish llmdocs

계획이 새 문서 또는 업데이트 문서로 표시한 모든 문서와 계획 이후 생성된 모든 문서(예: testing.md)에 계획이 확인한 HEAD 스탬프를 찍습니다. 스탬프는 문서 끝에 있는 마커 줄, 즉 해당 커밋을 명명하는 HTML 주석입니다. finish는 변경되지 않은 문서와 집중 영역 밖의 문서는 그대로 두고, 리포지토리에 커밋이 없으면 아무것도 스탬프를 찍지 않습니다. 종료 코드 4는 계획된 문서가 누락되었음을 의미합니다. 작성하고 finish를 다시 실행하세요.

• stamp를 직접 호출하거나 마커 줄을 직접 작성/편집하지 마세요. finish가 작성합니다.
• 마커는 메타데이터입니다. 히스토리 기록 금지 규칙이 적용되지 않습니다.

---

4. 요약 출력

실행 후 이 요약을 출력하세요. 실행에서 각 줄을 채우고 목록이 비어 있으면 "없음"을 작성하세요. 스탬프 아래에는 finish 자체의 줄을 문서당 하나씩 그대로 복사하세요. SHA를 절대 작성하지 말고, finish가 출력하지 않은 단어를 절대 추가하지 마세요.

기능을 제거하기 위해 바뀐 문장은 제거 항목입니다. 사라진 문구와 함께 제거됨 아래에 이름을 지정하세요. 동일한 줄이 여전히 존재하더라도 마찬가지입니다.

코드가 문자 카운팅을 제거한 실행의 채워진 예시입니다.

생성된 파일: 없음
수정된 파일: CLAUDE.md, .llmdocs/api.md
추가, 업데이트 또는 제거된 CLAUDE.md 섹션: 주요 개념 업데이트
코드와 모순되어 제거됨:
- CLAUDE.md: 목적 줄에서 "또는 문자", 그리고 --chars 주요 개념
- .llmdocs/api.md: count_chars 행
스탬프됨:
- 스탬프됨 CLAUDE.md (마커)
- 스탬프됨 .llmdocs/api.md (마커)

변경 사항이 문서 업데이트를 필요로 하지 않는 경우, 요약 위에 "문서 변경 사항 없음"을 작성하세요.