Living Docs (ldoc)

프로젝트의 지식과 실행 계획을 통합 관리하는 문서 시스템입니다.

Instructions

프로젝트 자동 인식

모든 워크플로우 시작 전에 프로젝트를 자동으로 확인합니다:

1. 현재 경로에서 프로젝트명 추출

   • ~/repos/{project}/... 패턴에서 {project} 추출
   • 프로젝트명 정제: _slot숫자 제거, 끝 숫자 제거
   • 없으면 사용자에게 질문

2. 문서 디렉토리 확인 및 생성

   • ~/docs/{project}/ 확인
   • 없으면 생성 제안: mkdir -p ~/docs/{project}/{knowledge,decisions,todos}

3. 사용자 확인: "{project} 프로젝트 맞나요?"

문서 위치 및 파일명 규칙

모든 문서는 ~/docs/{project}/ 아래 저장 (knowledge/, decisions/, todos/, requirements/)

파일명: kebab-case, 2-4단어, Self-descriptive

상세 규칙: REFERENCE.md 참조

워크플로우 1: 지식 문서 업데이트

사용자가 "X 문서 업데이트" 요청 시:

0. 프로젝트 확인 (위 "프로젝트 자동 인식" 절차에 따라 자동 수행)

1. 문서 확인

   Read ~/docs/{project}/knowledge/{category}/{topic}.md
   

2. 업데이트 유형 판단 사용자 요청과 변경 내용을 보고 둘 중 하나 선택:

   경로 A: 간단한 수정 (오타, 내용 추가, 포맷 정리 등)

   • "어떤 내용을 업데이트할까요?" 물어보기
   • 내용 수정
   • updated: 필드만 갱신 (오늘 날짜)
   • 히스토리 생략 가능
   • 변경 사항 요약 후 완료

   경로 B: 중요한 변경 (정책 변경, 아키텍처 수정, 설정 값 변경 등)

   • "어떤 내용을 업데이트할까요?"
   • "변경 이유를 알려주세요"
   • "영향받는 부분이나 관련 문서가 있나요?"
   • 필요시 추가 정보 요청
   • updated: 필드 갱신
   • "## 현재 상태" 섹션 업데이트
   • "## 히스토리" 섹션 최상단에 엔트리 추가:

     ### YYYY-MM-DD: [변경 제목]
     **변경 내용:**
     - [구체적 변경사항]
     
     **이유:**
     - [변경 이유]
     
     **영향:**
     - 관련 문서: [[doc-id]]
     - 관련 TODO: [[todo-id]]
     
     ---
     

   • 관련 문서에 역참조 추가 제안
   • 필요시 TODO 생성 제안

3. 확인

   • 변경 사항을 사용자에게 요약
   • 추가 업데이트 필요 여부 확인

4. Git 커밋

   cd ~/docs/{project} && git add knowledge/{category}/{topic}.md && git commit -m "docs(knowledge): update {category}/{topic} - {변경 요약}"
   

5. 자동 건강도 체크 (워크플로우 10)

   • 문서 크기 확인 (300+ 줄 시 분할 제안)
   • 중복 가능성 확인 (태그 80%+ 중복 시 병합 제안)
   • 이슈 발견 시 즉시 알림 및 리팩토링 제안

워크플로우 2: 의사결정 기록

사용자가 "X 결정 기록해줘" 요청 시:

1. 템플릿 사용 templates/decision.md를 기반으로 새 문서 생성

2. 사용자와 대화

   • "어떤 결정을 했나요?"
   • "이유는 무엇인가요?"
   • "어떤 대안을 고려했나요?"
   • "어떤 영향이 있나요?"

3. 문서 생성

   Write ~/docs/{project}/decisions/{slug}.md
   

   Frontmatter:

   • id: dec-{slug}
   • decided: 오늘 날짜
   • impacts: 영향받는 문서 ID 배열 (사용자에게 확인)

4. 관련 문서 업데이트

   • 영향받는 문서들의 references: 에 이 결정 추가
   • 필요시 TODO 생성 제안

5. Git 커밋

   cd ~/docs/{project} && git add decisions/{slug}.md && git commit -m "docs(decision): add {slug}"
   

6. 자동 건강도 체크 (워크플로우 10)

   • 유사 결정 문서 중복 확인
   • 이슈 발견 시 알림

워크플로우 3: TODO 생성 및 관리

사용자가 "X 작업 TODO 만들어줘" 요청 시:

1. 작업 분석 (복수 작업 감지)

사용자 요청에서 복수 작업 패턴 확인:

• 쉼표 분리: "A, B, C 구현"
• 접속사: "A와 B 작업", "A, B, 그리고 C"
• 나열: "1. A 2. B 3. C"
• 명시적 복수: "5개 리소스", "여러 컴포넌트"

2. 분할 제안 (복수 감지 시)

사용자에게 확인:

다음 작업들을 각각 별도 TODO로 만들까요?
- {작업1-slug}.md
- {작업2-slug}.md
- {작업3-slug}.md

[1] 네, 각각 분할 (권장)
[2] 아니요, 하나로 통합

Slug 생성 원칙: Self-Descriptive (파일명만 봐도 작업 파악 가능)

상세 규칙: resources/07-todo-naming-guide.md 참조

3. 작업 간 관계 확인 ([1] 선택 시)

"작업 간 순서가 있나요?"

• [1] 순차 (A → B → C): depends-on 체인 설정
• [2] 병렬 (동시 진행): 공통 태그만 추가

4. 각 TODO 정보 수집

각 작업마다:

• "작업 내용을 설명해주세요"
• "완료 조건은 무엇인가요?"
• "관련 문서나 결정이 있나요?"
• "마감일이 있나요?"

5. 문서 생성

단일 작업 또는 [2] 선택 시:

Write ~/docs/{project}/todos/{slug}.md

복수 작업 분할 ([1] 선택 시):

# 병렬 작업
Write ~/docs/{project}/todos/{작업1-slug}.md  # depends-on: []
Write ~/docs/{project}/todos/{작업2-slug}.md  # depends-on: []
Write ~/docs/{project}/todos/{작업3-slug}.md  # depends-on: []

# 순차 작업
Write ~/docs/{project}/todos/{작업1-slug}.md  # depends-on: []
Write ~/docs/{project}/todos/{작업2-slug}.md  # depends-on: [todo-{작업1-slug}]
Write ~/docs/{project}/todos/{작업3-slug}.md  # depends-on: [todo-{작업2-slug}]

모든 TODO에 공통 태그 추가 (그룹 식별용)

6. 관련 문서 링크

관련 지식/결정 문서에 역참조 추가

7. Git 커밋

# 단일 TODO
cd ~/docs/{project} && git add todos/{slug}.md && git commit -m "docs(todo): add {slug}"

# 복수 TODO
cd ~/docs/{project} && git add todos/{작업*}.md && git commit -m "docs(todo): add {작업명} tasks ({count}개)"

8. 자동 건강도 체크 (워크플로우 10)

• 중복 TODO 확인
• 이슈 발견 시 알림

워크플로우 4: 현황 파악

사용자가 "뭐 해야해?", "TODO 목록", "이번 주 할 일" 요청 시:

1. Active TODO 파일 검색 (completed 제외)

   Glob ~/docs/{project}/todos/*.md
   

   주의: todos/*.md 패턴은 todos/completed/ 하위 파일은 제외

2. 각 파일 분석

   • Read로 frontmatter만 빠르게 확인
   • status: 필드 확인 (pending, in-progress)

3. 필터링 및 정렬

   • "이번 주" 요청 시: 이번 주 월요일~일요일 범위 deadline만
   • deadline이 가까운 순
   • priority 높은 것 우선

4. 사용자에게 리포트

   현재 진행 중: 3개
   - [todo-002] {작업명} (마감: MM/DD, 우선순위: 높음)
   
   대기 중: 5개
   - [todo-007] {작업명} (마감: MM/DD)
   
   완료 (이번 달): 12개
   → todos/completed/YYYY-MM/ 참조
   

워크플로우 5: 지식 탐색 (Wiki 스타일)

사용자가 "X 관련 정보", "X 문서 찾아줘", "이 문서와 관련된 문서는?" 요청 시:

핵심 원칙: Read 최소화, Grep으로 후보 좁히기

1. 구조 파악: lsd --tree로 전체 구조 확인
2. 인덱스 탐색: Grep으로 키워드/태그/ID 검색
3. 검색 전략 선택:
   • 키워드 검색
   • 연결 탐색 (Forward Links/Backlinks)
   • 태그 기반 탐색
   • 상태 기반 필터링
4. 상세 분석: 필요한 문서만 Read
5. 종합 리포트: 관련 문서/TODO/의사결정 제공

상세 패턴: resources/knowledge-search-patterns.md 참조

워크플로우 6: 새 문서 생성

사용자가 "X 문서 만들어줘" 요청 시:

1. 문서 유형 확인

   • 지식 문서? → templates/knowledge.md
   • 의사결정? → templates/decision.md
   • TODO? → templates/todo.md

2. 사용자와 대화

   • 카테고리 확인 (architecture, security 등)
   • 초기 내용 수집

3. 템플릿 기반 생성 적절한 위치에 파일 생성

4. Git 커밋

   cd ~/docs/{project} && git add {문서경로} && git commit -m "docs({유형}): add {slug}"
   

5. 자동 건강도 체크 (워크플로우 10)

   • 문서 크기 및 중복 확인
   • 이슈 발견 시 즉시 알림

워크플로우 7: 문서 병합 (중복 방지)

문서 생성/업데이트 후 유사 문서 확인:

1. 유사 문서 탐색: 같은 카테고리, 키워드, 태그로 검색
2. 유사도 판단: 태그 50%+ 겹침 → 병합 고려
3. 사용자 제안: 병합 옵션 제시 (기존 문서 통합 / 새 문서 생성)
4. 병합 실행:
   • 기존 문서 통합 또는 새 문서 생성
   • 히스토리 기록 (간결성 원칙: 3-5줄)
   • 참조 업데이트 (Grep으로 검색)
   • Git 커밋

워크플로우 8: Git 관리

모든 문서 변경 사항은 Git으로 추적합니다:

• 글로벌 규칙: ~/dots/prompts/rules/commit.md 준수
• Living Docs 커밋 포맷: REFERENCE.md 참조
• 프로젝트 문서 디렉토리 생성 시 자동으로 Git 초기화 (저장소 없는 경우)

워크플로우 9: TODO 상태 관리 및 완료 처리

A. 상태 변경

사용자가 "X 작업 시작", "X 작업 진행 중", "X 작업 완료" 요청 시:

1. TODO 파일 확인 및 상태 업데이트

   • pending → in-progress: status: in-progress 설정
   • in-progress → done: status: done + completed: YYYY-MM-DD 설정

2. 히스토리 추가 (간결성 원칙 준수: 3-5줄)

B. 완료 후 처리

TODO가 status: done이 되면 completed/ 디렉토리로 이동 (기본 동작):

1단계: Completed로 이동 (필수)

# 완료 월별 디렉토리 생성 (없는 경우)
mkdir -p ~/docs/{project}/todos/completed/YYYY-MM

# TODO 파일 이동
mv ~/docs/{project}/todos/{slug}.md \
   ~/docs/{project}/todos/completed/YYYY-MM/{slug}.md

완료 메시지: "✅ TODO [[todo-{slug}]] 완료 → todos/completed/YYYY-MM/로 이동"

2단계: 추가 처리 (선택)

사용자에게 선택지 제안:

옵션 1: 이대로 보관 (기본, 빠름)

• completed/에 보관하여 작업 히스토리 유지
• 나중에 회고, 참고 자료로 활용

옵션 2: Knowledge로도 통합 (재사용 가치 있는 경우)

1. Category 결정 (architecture, security, operations 등)
2. 관련 문서 찾기 (Grep, Glob로 검색)
3. 통합 가치 판단 (체크리스트)
4. 문서 업데이트 또는 신규 생성
5. completed/에는 그대로 유지 (삭제 안 함)

상세 절차: resources/todo-completion-guide.md 참조

옵션 3: 삭제 (정말 불필요한 경우)

• completed/에서도 제거
• Git 히스토리에만 남음

사용자 확인: "[1] 이대로 보관 (기본) / [2] Knowledge로도 통합 / [3] 삭제"

워크플로우 10: 문서 건강도 자동 체크

실행 시점:

• 워크플로우 1, 2, 3, 6 완료 후 자동 실행
• 사용자가 "찾기 힘들어", "중복", "문서 정리" 언급 시

Subagent 호출:

Task(
  subagent_type="ldoc-automation",
  prompt="WF10 건강도 체크: ~/docs/{project}/"
)

자동 체크 항목:

• 문서 크기: 300+ 줄 → 분할 제안
• 중복 가능성: 태그 80%+ 중복 → 병합 제안
• 참조 건강도: 끊어진 링크, 고아 문서

상세 로직: resources/health-check.md 참조

워크플로우 11: Completed TODO 아카이브 (선택)

실행 시점: "오래된 TODO 정리", "completed 정리" 요청 시

대상: 6개월 이상 경과한 completed TODO

옵션:

1. 유지 (활발한 프로젝트)
2. Git 압축 후 삭제 (완료된 프로젝트)
3. 아카이브 디렉토리로 이동 (장기 프로젝트)

상세 절차: resources/completed-archive-policy.md 참조

워크플로우 12-14: 요구사항 관리

요구사항 문서 작성, 상태 변경, 검색/분석을 위한 워크플로우입니다.

• WF12: 요구사항 작성 (EARS 패턴 기반)
• WF13: 상태 변경 (draft → proposed → approved → implemented)
• WF14: 검색 및 분석 (시스템별, 상태별, 카테고리별)

상세 절차: resources/08-requirements-workflows.md 참조 EARS 패턴: resources/ears-guide.md 참조

중요 원칙

1. 사용자 중심: 항상 사용자에게 확인하고 대화하며 진행
2. 명확한 커뮤니케이션: 변경 전 요약, 변경 후 확인
3. 일관성: 모든 문서는 템플릿 구조 유지
4. 추적 가능성: 히스토리와 참조를 통한 변경 추적
5. 단순함: 복잡한 스크립트 대신 Claude의 판단 활용
6. 자동 건강도 관리: 문서 작성 중 자동으로 정리 필요성 판단
7. 간결성: 각 섹션은 핵심만 간결하게 작성 (상세: resources/writing-guidelines.md)

Examples

지식 문서 업데이트

User: "{topic} 문서 업데이트" → 워크플로우 1 → 사용자 대화 → 히스토리 추가 (3-5줄) → Git 커밋

TODO 현황 파악

User: "이번 주 할 일" → 워크플로우 4 → Glob + Read → 우선순위/마감일 정렬 → 리포트 제공

의사결정 기록

User: "{주제} 결정 기록" → 워크플로우 2 → 템플릿 기반 생성 → 사용자 대화 (이유, 대안, 영향) → 관련 문서 링크 → Git 커밋

TODO 생성 (복수 분할)

User: "User, Post, Comment 리소스 구현해줘" → 워크플로우 3 → 복수 감지 → 분할 제안 → resource-user.md, resource-post.md, resource-comment.md 생성 → 공통 태그 추가

TODO 완료 및 처리

User: "{task} 완료" → 워크플로우 9 → completed/로 이동 (필수) → 추가 처리 선택 ([1] 보관 / [2] Knowledge 통합 / [3] 삭제)

요구사항 작성

User: "로그인 요구사항 작성" → 워크플로우 12 → EARS 패턴 선택 → 사용자 대화 (시스템, 동작, 수용기준) → 문서 생성 → Git 커밋

요구사항 승인

User: "req-auth-login 승인" → 워크플로우 13 → status: approved → 히스토리 추가 → Git 커밋 → "구현 TODO 생성할까요?" 제안

CLI Scripts

ldoc CLI로 TODO 목록 조회, 아카이브, 건강도 체크를 수행합니다.

상세 사용법: resources/09-cli-usage.md 참조

Technical Details

상세한 템플릿 구조와 frontmatter 형식은 REFERENCE.md를 참조하세요.