absorb

name	absorb
description	지정 디렉터리의 문서를 심층 분석하여 지식을 추출하고, 기존 문서 갱신 + 신규 문서 생성으로 프로젝트 지식 베이스에 반영합니다.
when_to_use	디렉터리 문서 일괄 흡수, 문서 10건 이상 정리, 지식 베이스에 반영. 단건 1~3건은 learn.
disable-model-invocation	true
allowed-tools	Read, Write, Edit, Glob, Grep, Bash, Agent
effort	high

역할

지정 디렉터리의 모든 문서를 심층 분석하여:

1. 추출: 영구 보존 가치가 있는 지식을 유형별로 분류
2. 교차 검증: 기존 지식 베이스와 대조하여 신규/보강/충돌/낡음을 판별
3. 반영: 기존 문서 갱신 + 신규 문서 생성으로 지식 베이스에 체계적 반영

핵심 원칙:

• "So What" 필터: "6개월 후 새 팀원이 읽었을 때 유용한가?" 이 기준을 통과한 지식만 반영
• 출처(Provenance) 추적: 모든 반영 항목에 (출처: {파일명}:{섹션}) 표기
• 충돌은 사용자 판단: 기존 내용과 모순되면 절대 자동 해결하지 않음

톤: 체계적이고 분석적. 양보다 질.

외부 데이터 의존

데이터	경로	필수/선택	부재 시 동작
프로젝트 컨텍스트	CLAUDE.md	선택	일반 SW 가정으로 진행, [프로젝트 규칙 미확인] 태그
봇 인덱스	bot/INDEX.md 또는 .local.claude/ONBOARDING.md	선택	디렉터리 Glob 으로 fallback
비즈니스 규칙	.local.claude/biz-rules.md	선택	Tier 1(도메인 무관) 점검만 수행
모듈 상세	.local.claude/modules/{name}.md	선택	코드 Grep 직접 fallback
원본 문서	.local.claude/docs/, .local.claude/docs/parsed/	선택	"흡수 대상 없음" 안내 후 종료
absorb-log	.local.claude/docs/absorb-log.md	선택	증분 모드 비활성, 전체 재처리
기존 sink 문서	CLAUDE.md, biz-rules.md, modules/, customers/	선택	Phase 2.5 역읽기 생략, 직접 신규 생성

입력 처리

$ARGUMENTS로 디렉터리 경로 또는 명령을 받는다.

입력	동작
{디렉터리 경로}	해당 디렉터리 전체 문서 흡수
list	흡수 이력 대시보드 표시
--force {디렉터리 경로}	이미 흡수된 파일 포함 전체 재흡수
(빈 입력)	사용자에게 디렉터리 경로 질문

경로 정규화:

• 상대 경로는 프로젝트 루트 기준으로 해석
• .local.claude/ 접두사는 생략 가능. 생략 시 자동 보완 시도

---

프로세스

Phase 1: 정찰 (Reconnaissance)

[1M 활용] 다음을 단일 메시지에서 병렬로 호출:

• Glob: {path}/**/*.md, {path}/**/*.txt, 하위 디렉터리 전체 재귀 탐색
• Read 병렬: .local.claude/docs/absorb-log.md, CLAUDE.md, bot/INDEX.md/ONBOARDING.md, biz-rules.md, team.md (역읽기 후보 sink 파일 사전 로드)
• Bash: wc -l 규모 집계, mtime 비교(stat 또는 find -newer) 등 파일 메타데이터 병렬 수집

디렉터리를 스캔하여 전체 윤곽을 파악한다.

1. 파일 목록 수집: Glob으로 {path}/**/*.md + {path}/**/*.txt 수집

   • 비텍스트 파일(이미지, 바이너리)은 목록에서 제외하고 안내
   • 빈 디렉터리면 안내 후 종료
   • 하위 디렉터리도 재귀 포함

2. 규모 집계: 파일 수, 총 줄 수 산출 (Bash wc -l)

3. 흡수 이력 대조: .local.claude/docs/absorb-log.md를 읽어 이미 처리된 파일 식별

   • 흡수 완료 파일: 수정일이 흡수일 이후면 재처리 대상, 아니면 스킵
   • --force 옵션이면 전부 대상

4. 자기 참조 검사: .local.claude/ 하위의 영구 참조 문서(modules/, be-guide/, fe-guide/, customers/, ddl/, people/, adr/)를 대상으로 지정하면 경고:

   "이 디렉터리는 지식 베이스의 일부입니다. 흡수 대상이 아닌 반영 대상입니다. 정말 진행하시겠습니까?"

5. 정찰 보고: 사용자에게 간략 보고 후 진행 여부 확인:

   대상: .local.claude/meetings/ (4개 파일, 약 350줄)
   - 신규: 2개 (2026-04-15-주간회의.md, 2026-04-13-스프린트.md)
   - 이전 흡수: 2개 (스킵)
   진행하시겠습니까?
   

---

Phase 2: 심층 분석 (Deep Analysis)

모든 대상 파일을 읽고 지식을 추출한다.

규모별 전략

규모	기준	전략
소	파일 5개 이하 AND 총 300줄 이하	메인에서 직접 처리
중	파일 6~20개	서브에이전트 2개 병렬 (파일 균등 분배)
대	파일 21개+	서브에이전트 3개 병렬 (파일 균등 분배)

서브에이전트 프롬프트

서브에이전트에게 위임할 때 다음을 전달:

• 담당 파일 목록 (절대 경로)
• 추출 유형 테이블 (아래)
• "So What" 필터 기준
• 기존 지식 베이스의 핵심 sink 파일 경로 (Phase 2.5에서 역읽기하므로 서브에이전트는 추출에만 집중)

각 서브에이전트는 JSON-like 구조로 추출 결과를 반환한다.

추출 유형

유형	추출 대상	예시
사실(Fact)	검증 가능한 구체적 정보	"{닉네임} PO 합류 (YYYY.MM~)"
결정(Decision)	합의되거나 지시된 방향	"배포 순서를 고객사 먼저, SaaS 나중으로 전환"
규칙(Rule)	반복 적용되는 비즈니스/기술 규칙	"중간 수시 배포 금지"
관계(Relation)	엔티티 간 연결	"{닉네임}은 결제 모듈 담당"
타임라인(Timeline)	시간 순서가 중요한 이벤트	"YYYY-MM-DD {모듈} 운영 오픈"
인사이트(Insight)	패턴, 경향, 교훈	"{팀명} {고객사} 업무 비중 N%, 과의존"

"So What" 필터

추출된 모든 항목에 적용:

반영 대상 (통과):

• 반복 적용되는 규칙/정책
• 구조적 변경 (팀, 인프라, 아키텍처)
• 의사결정 및 그 근거
• 상태 전이 규칙
• 인원 변동 (합류, 퇴사, 발령, 역할 변경)
• 고객사 특성/요구사항
• 마일스톤/배포 이력

제외 대상 (필터링):

• 일회성 업무 현황 ("{닉네임}이 오늘 재택", "이번 주 야근")
• 이미 코드/git history에 기록된 사실
• 개인적 감상이나 의견
• 구체적 일정 조율 내용 (언제 미팅할지 등)

소스 품질 평가

OCR 파싱 문서 등에서 다음을 감지하면 해당 영역의 신뢰도를 낮춤:

• 깨진 문자/특수문자 연속
• 테이블 구조 붕괴
• 문장 중간 절단

보고서에 [WARN] 소스 품질 주의 표기.

교차 문서 종합

여러 파일에 걸쳐 등장하는 동일 주제를 하나로 통합:

• 동일 사건의 다른 관점은 통합하여 풍부하게
• 시간 순서가 있으면 최신 정보를 우선
• 모순되는 정보는 양쪽 모두 보존하고 충돌로 분류

---

Phase 2.5: 기존 지식 베이스 역읽기 (Reverse Scan)

[1M 활용] 메인에서 직접 다중 파일 동시 Read 후 교차 분석:

• 로드: Phase 2 추출 결과에 등장한 카테고리별 sink 문서를 한꺼번에 로드: team.md, customers/{name}.md 전체, biz-rules.md, biz-rules-detail.md, modules/{name}.md 관련, INFRASTRUCTURE.md, be-guide/be-convention-final.md, fe-guide/fe-convention-final.md
• 교차 분석: {새 추출 지식} vs {기존 sink 내용}. 낡은 지식(STALE) 감지, 커버리지 갭 감지, 순환 참조(기존이 이미 인용) 방지
• 한계: 총 로드 추정 토큰 ~600K(1M 컨텍스트의 60%; 줄 수로 대략 가늠) 근접 시 추출 카테고리별로 Phase 2.5 를 분리 실행 권장.

흡수 대상만 읽는 것이 아니라, 기존 지식 베이스의 관련 문서도 함께 읽는다.

역읽기 대상 결정

Phase 2에서 추출된 지식의 카테고리에 따라 읽을 기존 문서를 결정:

추출 카테고리	역읽기 대상
팀/인원 관련 추출물 있음	team.md
고객사 언급 있음	customers/{해당 고객사}.md
상태 전이/비즈니스 규칙	biz-rules.md (자동 로드되므로 이미 확인 가능)
모듈 관련	modules/{해당 모듈}.md
인프라/배포	INFRASTRUCTURE.md
컨벤션	be-guide/be-convention-final.md 또는 fe-guide/fe-convention-final.md

모든 관련 문서를 읽을 필요 없음. 추출된 지식이 가리키는 문서만 선택적으로 읽는다.

두 가지 추가 탐지

1. 낡은 지식 감지 (Stale Detection)

   새 문서의 정보가 기존 문서와 모순될 때, 기존 문서가 오래된 것일 수 있음.

   예: 회의록 "배포 순서를 고객사 먼저, SaaS 나중으로 변경" vs INFRASTRUCTURE.md "SaaS 먼저, 고객사 나중 순서" 이 경우 기존 문서 갱신 필요로 플래그

   단, 판단이 애매하면 충돌로 분류하여 사용자에게 질문.

2. 커버리지 갭 감지 (Coverage Gap)

   흡수 대상 문서에서 자주 언급되지만 지식 베이스에 빈약한 영역을 식별.

   예: "주간보고에서 BizLink 5회 언급, modules/bizlink.md는 개요만" 이 경우 보고서에 "심층 분석 권장" 표기

순환 참조 방지

daily/briefing 등의 문서가 biz-rules.md나 bot/*.md (또는 ONBOARDING.md) 의 내용을 인용하고 있는 경우, 그것을 "새 지식"으로 오인하지 않도록:

• 추출된 표현이 기존 지식 베이스에 이미 동일/유사하게 존재하면 SKIP

---

Phase 3: 반영 계획 (Reflection Plan)

추출된 지식을 어디에 반영할지 결정한다.

경로 A: 기존 문서 갱신

지식 유형	반영 대상 후보	판단 기준
상태 전이, 비즈니스 로직	biz-rules.md / biz-rules-detail.md	상태 코드, 전이 조건
모듈 아키텍처, 서비스 동작	modules/{name}.md	모듈명, 서비스명, 테이블명
팀 구조, 인원 변동	team.md	사람 이름, 합류/퇴사/발령
고객사 특성, 요구사항	customers/{name}.md	고객사명
아키텍처 흐름, 진입점	bot/*.md 또는 ONBOARDING.md	요청 흐름, 모듈 매핑
서버, 배포, 인프라	INFRASTRUCTURE.md	IP, 배포, CI/CD
코딩 패턴, 컨벤션	be-guide/ / fe-guide/	코딩 규칙, 패턴
프로젝트 규칙 (최상위)	CLAUDE.md	금지사항, 공통 모듈, 보안
대화 간 지속 정보	auto memory	프로젝트 상태, 팀 역학

CLAUDE.md 반영 시: 현재 줄 수를 체크. 150줄 상한에 근접하면 .local.claude/ 하위 문서로 분리 제안.

경로 B: 신규 문서 생성

기존 문서에 매칭되지 않는 지식이 충분히 모이면 신규 문서 생성을 제안한다. ("충분히" = 단일 사실 1건으로 파일 생성 안 함. 해당 주제에 대한 추출물이 3건 이상이거나, 구조화할 수 있는 양이 될 때.)

상황	생성 대상	템플릿 소스
미등록 고객사 정보 발견	customers/{name}.md	기존 customers/*.md 구조 참조
미등록 모듈 분석 결과	modules/{name}.md	modules/_TEMPLATE.md 사용
새 프로젝트 맥락 발견	projects/{name}/STATUS.md	기존 projects/*/STATUS.md 구조 참조
새 비즈니스 규칙 카테고리	biz-rules.md 신규 섹션	기존 섹션 구조 참조
기존 sink에 안 맞는 체계적 지식	사용자와 협의 후 결정	없음

신규 문서 생성 시:

• 반드시 기존 유사 문서의 구조/포맷을 Read하여 일관성 유지
• 최소한의 골격만 생성. 흡수된 내용만 채우고, 미확인 섹션은 [미확인]으로 표기

다중 sink 반영

하나의 지식이 여러 문서에 걸칠 수 있음.

예: "{고객사} 서버 통합"은 customers/{고객사}.md + INFRASTRUCTURE.md + 관련 modules/*.md에 반영

이 경우 하나의 추출 항목에 반영처를 복수로 지정하되, 각 문서에 맞는 관점으로 기술한다:

• customers 파일: 고객 관점 (서비스 영향)
• INFRASTRUCTURE 파일: 인프라 관점 (서버 구성 변경)
• modules 파일: 기술 관점 (코드/설정 변경)

각 반영 항목의 분류

모든 반영 항목을 다음으로 분류:

분류	의미	행동
NEW	기존 문서에 없는 신규 지식	추가
ENRICH	기존 내용을 보강하는 상세 정보	병합
STALE	기존 내용이 오래되어 갱신 필요	교체 (사용자 확인 후)
CONFLICT	기존 내용과 모순	사용자 판단 필수
SKIP	이미 기록됨	건너뜀

---

Phase 4: 보고 + 승인

사용자에게 다음 형식으로 보고한다.

대량 추출(30건+)인 경우 카테고리별로 그룹화하고 각 그룹 내에서 중요도순 정렬: 결정 > 규칙 > 사실 > 관계 > 타임라인 > 인사이트.

## /absorb 보고서: {디렉터리 경로}

### 분석 개요
| 항목 | 값 |
|------|---|
| 대상 디렉터리 | {path} |
| 파일 수 | N개 (총 N줄) |
| 추출 지식 | 사실 N, 결정 N, 규칙 N, 관계 N, 타임라인 N, 인사이트 N |
| 소스 품질 | [OK] 양호 / [WARN] 일부 주의 / [FAIL] 저품질 |
| 반영 계획 | 기존 갱신 N건, 신규 생성 N건, 낡은 지식 N건, 충돌 N건, 건너뜀 N건 |

### 기존 문서 갱신: NEW + ENRICH (N건)
| # | 대상 파일 | 변경 내용 | 유형 | 출처 |
|---|----------|----------|------|------|
| 1 | team.md | {닉네임} 경영지원 합류 (MM~) 추가 | NEW | meetings/MM-DD.md 1절 |
| 2 | customers/{고객사}.md | 서버 통합 일정 보강 | ENRICH | meetings/MM-DD.md 2절 |

### 신규 문서 생성 (N건)
| # | 생성 경로 | 내용 요약 | 근거 |
|---|----------|----------|------|
| 1 | customers/{새 고객사}.md | 신규 고객사 프로필 (계약/모듈/담당자) | 주간보고 N회 언급, 기존 프로필 없음 |

### 낡은 지식 감지 (N건): 기존 문서 갱신 권고
| # | 기존 문서 | 현재 기록 | 갱신 필요 내용 | 근거 |
|---|----------|----------|-------------|------|
| 1 | INFRASTRUCTURE.md 배포 절 | SaaS 먼저, 고객사 나중 순서 | 고객사 먼저, SaaS 나중으로 변경됨 | meetings/04-15.md 1절 |

### 충돌 (N건): 사용자 판단 필요
| # | 기존 내용 | 새 정보 | 대상 파일 | 출처 |
|---|----------|--------|----------|------|

### 커버리지 갭 (N건): 심층 분석 권장
| # | 영역 | 현재 상태 | 소스 내 언급 빈도 | 제안 |
|---|------|----------|----------------|------|

### 건너뜀 (N건)
(이미 기록된 내용 요약. 상세 나열 불필요)

---
진행 옵션:
- **전체 반영**
- **선택 반영** (번호 지정, 예: 1,3,5)
- **충돌만 검토**
- **취소**

---

Phase 5: 실행 (Execute)

사용자 승인 후 반영을 실행한다.

실행 순서

1. 충돌 해결 (사용자가 선택한 방향으로)
2. 낡은 지식 갱신 (STALE 항목의 기존 내용 교체)
3. 기존 문서 갱신 (NEW, ENRICH)
4. 신규 문서 생성
5. absorb-log 업데이트

반영 방법

기존 문서 갱신:

• 반드시 Read 후 Edit 순서 (최신 상태 확인 후 수정)
• 변경 이력 테이블이 있는 문서 (biz-rules.md 등): | YYYY-MM-DD | absorb: {요약} | {소스 디렉터리} | 추가
• 추가 위치: 해당 문서의 관련 섹션 끝에 자연스럽게 삽입

신규 문서 생성:

• 기존 유사 문서를 Read하여 구조 참조
• Write로 생성
• 흡수된 내용만 채움. 미확인 영역은 [미확인]
• 첫 줄에 > 마지막 업데이트: YYYY-MM-DD | /absorb로 생성 표기

auto memory 반영:

• 대화 간 지속이 필요한 정보는 메모리 파일 생성/갱신 안내
• 직접 메모리에 쓰지 않고, 사용자에게 "이 정보는 auto memory에 저장하는 것이 적합합니다" 안내

완료 보고

## /absorb 완료: {디렉터리 경로}

### 반영 결과
| 대상 | 변경 | 건수 |
|------|------|------|
| team.md | 인원 추가 2건 | 2 |
| customers/{고객사}.md | 서버 통합 보강 | 1 |
| customers/{새 고객사}.md | **신규 생성** | 1 |

### 흡수 기록
- absorb-log.md에 N건 기록 완료
- 다음 `/absorb list`에서 확인 가능

### 후속 제안
- 커버리지 갭: modules/bizlink.md 심층 분석 필요
- 코드 검증 필요: [문서 기반] 태그 N건은 `/learn`으로 검증 권장

---

흡수 이력 추적

추적 파일

.local.claude/docs/absorb-log.md: 파일 단위 흡수 이력.

디렉터리 단위 추적은 증분 흡수에 결함이 있음 (새 파일 추가 시 누락). 파일 단위로 추적하되 디렉터리별 요약 뷰도 유지한다.

# 문서 흡수 이력

> /absorb 스킬이 자동 관리. 수동 편집 금지.

## 요약
| 디렉터리 | 최종 흡수 | 흡수/총 파일 | 반영 건수 |
|----------|---------|------------|----------|
| meetings/ | 2026-04-16 | 4/4 | 8 |

## 상세
| 파일 | 흡수일 | 반영 건수 | 반영처 | 상태 |
|------|--------|----------|-------|------|
| meetings/2026-04-15-주간회의.md | 2026-04-16 | 5 | team.md, INFRASTRUCTURE.md | 완료 |

증분 흡수 로직

같은 디렉터리를 다시 /absorb 하면:

1. absorb-log에서 해당 디렉터리의 기존 흡수 파일 목록 조회
2. 현재 디렉터리 파일과 비교:
   • 새 파일 (로그에 없음): 처리 대상
   • 수정된 파일 (수정일 > 흡수일): 재처리 대상
   • 변경 없는 파일: 스킵
3. --force 옵션이면 전부 처리

/absorb list 출력

## 흡수 현황 대시보드

### 최근 흡수
| 디렉터리 | 날짜 | 파일 | 반영 | 주요 반영처 |
|----------|------|------|------|-----------|
| meetings/ | 04-16 | 4 | 8 | team.md, INFRASTRUCTURE.md |
| docs/parsed/weekly/ | 04-16 | 52 | 23 | team.md, customers/*.md |

### 미흡수 디렉터리 (absorb-log에 기록 없음)
- .local.claude/reports/ (3 파일)
- .local.claude/projects/{project-name}/ (N 파일)

---

연동

스킬	관계	충돌 방지
/garden	garden이 docs 아카이브 시 absorb-log 확인. 미흡수 파일이면 /absorb 먼저? 안내	garden은 아카이브만, absorb는 반영만
/learn	개별 claim의 코드 레벨 검증이 필요하면 /learn으로 안내	learn은 단건 검증, absorb는 대량 분석
/parse-doc	parse-doc 산출물을 absorb 입력으로 사용 가능 (종속 아님)	독립
/briefing	briefing이 자동 갱신하는 modules/*.md와 중복 방지	absorb는 Phase 2.5 역읽기에서 briefing 반영분 감지하여 중복 스킵
/biz-rules	비즈니스 규칙 반영은 biz-rules.md 포맷에 맞춤	absorb가 반영 시 biz-rules.md의 기존 섹션 구조를 존중
/customer-profile	고객사 신규 생성 시 customer-profile 포맷 참조	absorb가 생성, 이후 관리는 customer-profile

---

제약조건

• 충돌 자동 해결 금지: 기존 내용과 충돌 시 반드시 사용자 판단
• CLAUDE.md 150줄 상한 체크: 초과 위험 시 하위 문서로 분리 제안
• 코드 검증 가능한 기술 주장은 Grep으로 확인 시도. 불가 시 [문서 기반] 태그
• 여러 디렉터리 순차 처리: 같은 sink에 동시 쓰기 방지
• 부분 승인 시 absorb-log에 "부분 흡수"로 기록, 미반영 항목 추적
• 빈 디렉터리 / 비텍스트 파일: 안내 후 스킵
• 자기 참조 방지: 영구 참조 문서를 대상으로 지정하면 경고
• 순환 참조 방지: 기존 지식 베이스에서 인용된 표현을 "새 지식"으로 오인하지 않음
• 대량 추출 시 우선순위 그룹화: 30건+ 추출 시 카테고리별 그룹화, 중요도순 정렬 (결정 > 규칙 > 사실 > 인사이트)
• 멱등성: 같은 디렉터리를 두 번 흡수해도 중복 항목 없음 (파일 단위 추적 + 역읽기로 보장)
• WebSearch 금지: 서브에이전트에는 WebSearch 도구가 없으므로 웹 검색이 필요한 판단은 메인에서 처리

검증 시나리오

공통 3블록(빈 / 부분 / 풀 데이터)은 CONTRACT 6-1절 참조.

이 스킬의 고유 실패 시나리오

[환경/규모] 신규 문서 21개 이상 일괄 흡수

• 신호: 입력 문서 수 ≥ 21 또는 총 라인 5만+
• 대응: 규모별 서브에이전트 병렬 모드로 분할(카테고리별 그룹화) + 진행률 보고

[데이터 결함] Phase 2.5 역읽기에서 기존 문서가 90일+ 경과

• 신호: 기존 도메인 문서 mtime 90일 초과
• 대응: [stale] 태그로 표시 + 사용자 확인(교체 / 병합 / 보존) 후 반영