llm-wiki-hub: Instructions file for Claude Code

LLM-Wiki-Hub — Claude Code 운영 규칙

이 저장소는 여러 독립 프로젝트의 상태를 읽기 전용으로 집계하는 매니징 허브다. 각 프로젝트 git 은 별도로 존재하며, 여기서는 절대 수정하지 않는다.

핵심 원칙

• 통합은 단방향(읽기)·멱등이다. 허브는 각 프로젝트를 들여다보기만 한다.
• wiki/ 의 생성물은 모두 파생물이다. 직접 편집하지 말고 항상 스크립트로 재생성한다.
• 프로젝트 상태를 바꿔야 하면, 그 변경은 해당 프로젝트의 STATUS.md 에서 하고 그 프로젝트 git 에 커밋한다.

생성물 (wiki/)

• index.md : 프로젝트별 요약·상세. 맨 위에 블로커/정체 경고 섹션. 각 프로젝트명은 상세 페이지로 링크.
• projects/<name>.md : 프로젝트별 상세 페이지. 최근 커밋 10개 + STATUS 메모 + 미커밋 파일 + 할일 전체 + ADR.
• todos.md : 모든 프로젝트의 미완료 할일(- [ ])을 한데 모은 통합 리스트.
• adr.md : 모든 프로젝트의 결정사항(ADR)을 한데 모은 목록.

작업 시작 시 (항상)

1. python scripts/aggregate.py 를 실행해 대시보드를 최신화한다.
2. wiki/index.md 를 읽고 전체 상태 + 경고(정체/블로커)를 파악한다.
3. 우선순위가 필요하면 wiki/todos.md 로 통합 할일을 본다.
4. 설계 맥락이 필요하면 wiki/adr.md 로 결정사항을 본다.

프로젝트 추가

• projects.txt 에 프로젝트 절대경로(또는 ~/...)를 한 줄 추가한다.
• 그 프로젝트 루트에 STATUS.md 가 없으면 templates/STATUS.md 를 복사하도록 제안한다. (반드시 그 프로젝트 git 에서 커밋하도록 안내)

프로젝트 상태 갱신

• 진행 상황·마일스톤·블로커가 바뀌면:
  • 해당 프로젝트의 STATUS.md 를 수정한다.
  • 그 프로젝트 디렉토리에서 git add STATUS.md && git commit 한다.
  • 허브로 돌아와 python scripts/aggregate.py 를 재실행한다.

정체/경고 동작

• 마지막 커밋이 LLMWIKIHUB_STALE_DAYS(기본 7일)를 넘으면 💤 정체로 표시된다.
• STATUS.md 의 status: blocked 는 🚫 로 경고 섹션 맨 위에 노출된다.

할일 수집 규칙

• 기본은 '할일 목적' 파일만 스캔한다: TODO.md, tasks.md, *-tasks.md, PLAN.md, *-plan.md, ROADMAP.md, STATUS.md 등. (설계문서·README·setup 문서의 체크박스 노이즈를 배제하기 위함)
• .venv/, node_modules/, vendor/, build/, dist/ 등 벤더/빌드 산출물 경로는 항상 제외된다. (단 wiki/ 는 제외하지 않는다 — 프로젝트가 거기에 진짜 계획 문서를 두기도 한다. 허브 자신의 생성물 자기참조는 위 task-명 글롭만으로 이미 막힌다.)
• 프로젝트가 다른 파일에 할일을 둔다면 그 프로젝트 STATUS.md 에 todos: 글롭으로 재정의한다. 예) todos: README.md, docs/*-tasks.md / 옛 전체 스캔은 todos: *.md.

ADR 수집 규칙

• 각 프로젝트의 docs/adr/, adr/, wiki/decisions/, decisions/ 중 처음 발견된 디렉토리의 *.md 를 모은다.
• 각 ADR 파일의 첫 # 제목 과 status: 줄을 읽어 표로 정리한다.

하지 말 것

• wiki/ 의 생성물(*.md, _sidebar.md) 직접 수정 금지 (다음 집계 때 덮어써짐). 단 wiki/index.html(docsify 뷰어 셸)은 집계가 안 건드리는 관리 자산이라 편집해도 된다.
• 각 프로젝트의 소스 코드를 허브에서 직접 건드리지 말 것. 작업은 그 프로젝트 git 안에서.
• 프로젝트 git 들을 하나로 합치지 말 것. 흩어진 상태가 정상이다.