name	living-docs
description	프로젝트 지식과 할 일(TODO/todo)을 관리합니다. 문서 작성/업데이트, TODO 생성/완료, 의사결정 기록, 작업 현황 파악 시 사용하세요. (user)

Living Docs

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

Instructions

프로젝트 자동 인식

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

현재 경로에서 프로젝트명 추출
- ~/repos/{project}/... 패턴에서 {project} 추출
- 프로젝트명 정제: _slot숫자 제거, 끝 숫자 제거
- 없으면 사용자에게 질문
문서 디렉토리 확인 및 생성
- ~/docs/{project}/ 확인
- 없으면 생성 제안: mkdir -p ~/docs/{project}/{knowledge,decisions,todos}
사용자 확인: "{project} 프로젝트 맞나요?"

문서 위치 및 파일명 규칙

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

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

상세 규칙: REFERENCE.md 참조

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

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

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

문서 확인

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

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

경로 A: 간단한 수정 (오타, 내용 추가, 포맷 정리 등)
- "어떤 내용을 업데이트할까요?" 물어보기
- 내용 수정
- updated: 필드만 갱신 (오늘 날짜)
- 히스토리 생략 가능
- 변경 사항 요약 후 완료
경로 B: 중요한 변경 (정책 변경, 아키텍처 수정, 설정 값 변경 등)
- "어떤 내용을 업데이트할까요?"
- "변경 이유를 알려주세요"
- "영향받는 부분이나 관련 문서가 있나요?"
- 필요시 추가 정보 요청
- updated: 필드 갱신
- "## 현재 상태" 섹션 업데이트
- "## 히스토리" 섹션 최상단에 엔트리 추가:
```
### YYYY-MM-DD: [변경 제목]
**변경 내용:**
- [구체적 변경사항]

**이유:**
- [변경 이유]

**영향:**
- 관련 문서: [[doc-id]]
- 관련 TODO: [[todo-id]]

---
```
- 관련 문서에 역참조 추가 제안
- 필요시 TODO 생성 제안
확인
- 변경 사항을 사용자에게 요약
- 추가 업데이트 필요 여부 확인

Git 커밋

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

자동 건강도 체크 (워크플로우 10)
- 문서 크기 확인 (300+ 줄 시 분할 제안)
- 중복 가능성 확인 (태그 80%+ 중복 시 병합 제안)
- 이슈 발견 시 즉시 알림 및 리팩토링 제안

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

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

템플릿 사용 templates/decision.md를 기반으로 새 문서 생성
사용자와 대화
- "어떤 결정을 했나요?"
- "이유는 무엇인가요?"
- "어떤 대안을 고려했나요?"
- "어떤 영향이 있나요?"
문서 생성
```
Write ~/docs/{project}/decisions/{slug}.md
```
Frontmatter:
- id: dec-{slug}
- decided: 오늘 날짜
- impacts: 영향받는 문서 ID 배열 (사용자에게 확인)
관련 문서 업데이트
- 영향받는 문서들의 references: 에 이 결정 추가
- 필요시 TODO 생성 제안

Git 커밋

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

자동 건강도 체크 (워크플로우 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):

동사 구체화: fix → correct/add/refactor/resolve
명사 구체화: types → nullable-field-types, auth → jwt-auth
길이 허용: 4-6 단어 OK (명확성 > 간결성)

예시:

❌ admin-api-fix-openapi-types
✅ admin-api-correct-openapi-nullable-field-types
❌ update-user-service
✅ add-email-verification-to-user-registration

체크: 파일명만 봐도 작업 내용 파악 가능한가?

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 목록", "이번 주 할 일" 요청 시:

Active TODO 파일 검색 (completed 제외)
```
Glob ~/docs/{project}/todos/*.md
```
주의: todos/*.md 패턴은 todos/completed/ 하위 파일은 제외
각 파일 분석
- Read로 frontmatter만 빠르게 확인
- status: 필드 확인 (pending, in-progress)
필터링 및 정렬
- "이번 주" 요청 시: 이번 주 월요일~일요일 범위 deadline만
- deadline이 가까운 순
- priority 높은 것 우선

사용자에게 리포트

현재 진행 중: 3개
- [todo-002] {작업명} (마감: MM/DD, 우선순위: 높음)

대기 중: 5개
- [todo-007] {작업명} (마감: MM/DD)

완료 (이번 달): 12개
→ todos/completed/YYYY-MM/ 참조

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

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

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

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

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

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

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

문서 유형 확인
- 지식 문서? → templates/knowledge.md
- 의사결정? → templates/decision.md
- TODO? → templates/todo.md
사용자와 대화
- 카테고리 확인 (architecture, security 등)
- 초기 내용 수집
템플릿 기반 생성 적절한 위치에 파일 생성

Git 커밋

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

자동 건강도 체크 (워크플로우 10)
- 문서 크기 및 중복 확인
- 이슈 발견 시 즉시 알림

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

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

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

워크플로우 8: Git 관리

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

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

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

A. 상태 변경

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

TODO 파일 확인 및 상태 업데이트
- pending → in-progress: status: in-progress 설정
- in-progress → done: status: done + completed: YYYY-MM-DD 설정
히스토리 추가 (간결성 원칙 준수: 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로도 통합 (재사용 가치 있는 경우)

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

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

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

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

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

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

실행 시점:

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

자동 체크 항목:

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

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

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

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

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

옵션:

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

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

워크플로우 12: 요구사항 문서 작성

사용자가 "X 요구사항 작성", "requirement 추가" 요청 시:

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

템플릿 사용 templates/requirements.md를 기반으로 새 문서 생성
EARS 패턴 결정 사용자와 대화하여 적절한 패턴 선택:
- "이 요구사항은 조건이 있나요? (상태/이벤트/기능)"
- "항상 적용되는 요구사항인가요?"
- "오류/예외 상황 처리인가요?"
패턴 선택 가이드: resources/ears-guide.md 참조
요구사항 정보 수집
- "어떤 시스템/컴포넌트에 대한 요구사항인가요?"
- "시스템이 어떻게 동작해야 하나요?"
- "수용 기준은 무엇인가요?"
- "관련 결정이나 문서가 있나요?"
EARS 문장 작성 선택한 패턴에 따라 요구사항 문장 구성:
- Ubiquitous: "The {system} shall {response}."
- State-Driven: "While {precondition}, the {system} shall {response}."
- Event-Driven: "When {trigger}, the {system} shall {response}."
- Optional Feature: "Where {feature}, the {system} shall {response}."
- Unwanted Behavior: "If {condition}, then the {system} shall {response}."
문서 생성
```
Write ~/docs/{project}/requirements/{category}/{slug}.md
```
Frontmatter:
- id: req-{category}-{slug}
- ears-pattern: 선택한 패턴
- system: 대상 시스템명
- status: draft
- category: functional | non-functional | constraint | interface
관련 문서 링크
- 관련 결정/지식 문서에 역참조 추가 제안
- 관련 요구사항이 있으면 depends-on 설정

Git 커밋

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

자동 건강도 체크 (워크플로우 10)
- 유사 요구사항 중복 확인
- 충돌하는 요구사항 경고

워크플로우 13: 요구사항 상태 변경

사용자가 "X 요구사항 승인", "X 요구사항 구현 완료" 요청 시:

요구사항 파일 확인 및 상태 업데이트
- draft → proposed: 검토 요청
- proposed → approved: 승인
- approved → implemented: 구현 완료
- 모든 상태 → deprecated: 폐기
히스토리 추가 (간결성 원칙: 3-5줄)
연동 작업
- approved → implemented: 관련 verified-by TODO/테스트 상태 확인
- deprecated: 영향받는 문서에 알림

Git 커밋

cd ~/docs/{project} && git add requirements/{category}/{slug}.md && git commit -m "docs(requirement): update {slug} status to {status}"

워크플로우 14: 요구사항 검색 및 분석

사용자가 "요구사항 현황", "시스템별 요구사항", "미구현 요구사항" 요청 시:

검색 기준 확인
- 시스템별: system: 필드로 필터링
- 상태별: status: 필드로 필터링
- 카테고리별: 디렉토리 또는 category: 필드
- EARS 패턴별: ears-pattern: 필드

Grep으로 필터링

# 상태별
Grep "status: approved" ~/docs/{project}/requirements/**/*.md

# 시스템별
Grep "system: auth-service" ~/docs/{project}/requirements/**/*.md

리포트 제공

요구사항 현황 ({project})

상태별:
- draft: 3개
- proposed: 2개
- approved: 5개 (구현 대기)
- implemented: 12개
- deprecated: 1개

시스템별:
- auth-service: 8개
- payment-service: 6개

우선순위별:
- critical: 2개 (approved)
- high: 4개

중요 원칙

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

Living Docs는 자동화 스크립트를 제공합니다.

스크립트 위치

scripts/
├── living-docs           # 메인 CLI 진입점
├── todo-list.sh          # TODO 목록 조회
├── todo-archive.sh       # 완료된 TODO 아카이브
├── health-check.sh       # 문서 건강도 체크
└── lib/
    ├── frontmatter.sh    # YAML 파싱 라이브러리
    └── utils.sh          # 공통 유틸리티

사용법

# 현황 요약
living-docs

# TODO 목록 조회
living-docs list
living-docs list -s pending
living-docs list --priority urgent

# 완료된 TODO 아카이브
living-docs archive              # dry-run (미리보기)
living-docs archive --execute    # 실제 실행

# 문서 건강도 체크
living-docs health
living-docs health --quick       # 빠른 체크
living-docs health --full        # 전체 체크

Proactive Triggers

다음 키워드 감지 시 스크립트 실행을 제안합니다:

키워드	스크립트	설명
"TODO 목록", "할 일", "뭐 해야"	`living-docs list`	TODO 목록 조회
"정리", "아카이브", "completed 정리"	`living-docs archive`	완료된 TODO 정리
"건강도", "문서 상태", "중복 확인"	`living-docs health`	문서 건강도 체크

의존성

yq: YAML frontmatter 파싱
rg (ripgrep): 빠른 파일 검색
jq: JSON 처리 (선택)

Technical Details

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

Install Skill

SKILL.md

Living Docs

Instructions

프로젝트 자동 인식

문서 위치 및 파일명 규칙

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

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

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

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

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

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

4. 각 TODO 정보 수집

5. 문서 생성

6. 관련 문서 링크

7. Git 커밋

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

워크플로우 4: 현황 파악

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

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

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

워크플로우 8: Git 관리

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

A. 상태 변경

B. 완료 후 처리

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

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

워크플로우 12: 요구사항 문서 작성

워크플로우 13: 요구사항 상태 변경

워크플로우 14: 요구사항 검색 및 분석

중요 원칙

Examples

지식 문서 업데이트

TODO 현황 파악

의사결정 기록

TODO 생성 (복수 분할)

TODO 완료 및 처리

요구사항 작성

요구사항 승인

CLI Scripts

스크립트 위치

사용법

Proactive Triggers

의존성

Technical Details