القائمة
디렉터리 내 모든 Markdown을 통합 이해해 AI 전용 bot/ + 사람 전용 human/ 으로 재구성하고, 메타 분석(모순, 맹점, 향후 방향)을 human/insights.md 로 도출합니다. 프로젝트 문서가 누적되어 읽기 비용이 커졌을 때 사용하세요.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
지정 디렉터리의 문서를 심층 분석하여 지식을 추출하고, 기존 문서 갱신 + 신규 문서 생성으로 프로젝트 지식 베이스에 반영합니다.
기술 의사결정 기록 (Architecture Decision Record). 중요한 기술적 결정의 맥락, 대안, 근거를 구조화하여 기록합니다.
현재 디렉터리의 내용을 분석하여 어떤 목적의 폴더인지 파악
슬랙/메일/메신저로 받은 업무 요청 메시지를 분석하여 의도, 핵심 내용, 판단, 액션 플랜, 대응 가이드를 정리합니다.
비즈니스 규칙, 도메인 규칙, 상태 전이 규칙을 하나의 문서로 관리합니다. 변경 이력이 누적됩니다.
열린 질문, 문제 해결, 기술 의사결정, 아이디어 발산을 구조화합니다. 회의록이나 메모 파일 경로를 인자로 전달하거나 직접 질문하세요.
| name | dualize-docs |
| description | 디렉터리 내 모든 Markdown을 통합 이해해 AI 전용 bot/ + 사람 전용 human/ 으로 재구성하고, 메타 분석(모순, 맹점, 향후 방향)을 human/insights.md 로 도출합니다. 프로젝트 문서가 누적되어 읽기 비용이 커졌을 때 사용하세요. |
| when_to_use | 문서를 bot과 human으로 이원화, 읽기 비용이 커진 문서 재구성. |
| argument-hint | <directory-path> [--archive-source] |
| allowed-tools | Read, Glob, Grep, Write, AskUserQuestion, Bash(mkdir *, ls *, find *, mv *, rm -rf *, wc *, date *, grep *, test *, sort *, head *, basename *, [ *) |
| effort | max |
| disable-model-invocation | true |
대상 디렉터리의 .md 문서들을 통합 이해한 뒤, 세 가지 산출물을 생성합니다.
bot/: AI 에이전트 단독 참조 사실 레이어. 표, 코드경로, 상태전이, 규칙, 중복 0, 1파일 1주제human/: 사람용 설명 레이어. Mermaid 다이어그램, 스토리텔링, AS-IS/TO-BEhuman/insights.md: 메타 분석. 원본에는 없지만 여러 문서를 한꺼번에 봤기에 드러나는 모순, 맹점, 반복 패턴, 향후 방향설계 원칙:
bot/ 에 단일 소스로 존재. human/ 은 "왜"만, human/insights.md 는 "그래서 앞으로 어떻게"--archive-source 플래그 시에만 archive/YYYY-MM-DD/ 로 이동find/wc/grep/mv 등 표준 유틸 사용, 경로 구분자 /. 실행 환경의 셸과 유틸 차이는 CLAUDE.md 또는 프로젝트 설정을 따른다 (특정 OS 가정 박지 않음)문서 탐색 진입점: bot/INDEX.md 는 AI 에이전트가 해당 디렉터리를 탐색할 때 우선 참조하는 진입점이다. 프로젝트가 "문서 탐색 우선순위" 규칙을 CLAUDE.md 에 두면 그와 연동된다 (전역 환경 가정은 두지 않음).
| 데이터 | 경로 | 필수/선택 | 부재 시 동작 |
|---|---|---|---|
| 프로젝트 컨텍스트 | 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 |
| 원본 디렉터리 | 대상 경로의 실제 파일들 | 필수 | "대상 디렉터리 부재" 안내 후 종료 |
| 기존 bot/human 구조 | {path}/bot/, {path}/human/ | 선택 | 처음부터 생성, 누적 병합 모드 비활성 |
| absorb-log | .local.claude/docs/absorb-log.md | 선택 | 증분 처리 불가, 전체 재처리 |
사용자와 에이전트가 헷갈릴 수 있는 네 스킬의 명확한 분기:
| 이럴 때 | 어떤 스킬 | 왜 |
|---|---|---|
만료 문서 식별, 아카이브, INDEX.md 갱신 | /garden | 문서 수명 관리 전담 |
| 새 지식을 기존 메모리, CLAUDE.md, 규칙에 통합 | /absorb | 지식 베이스 자동 반영 |
| CLAUDE.md 진단과 최적화 | /optimize-claude-md | 메모리 설정 점검 전담 |
| 누적된 프로젝트 문서를 AI와 사람 두 독자층에 재구성 + 메타 분석 | /dualize-docs | 출력 포맷 재구조화 + 1M context 기반 인사이트 |
조합 권장:
/dualize-docs 후 /garden: 재구성 후 원본 아카이브 정리/absorb 후 /dualize-docs: 지식 통합 후 프로젝트 문서 재구성/optimize-claude-md 는 독립적. 메모리 설정 전용$ARGUMENTS 에서 분리:
--archive-source 플래그 (선택)인자 비었으면 중단:
사용법: /dualize-docs <directory-path> [--archive-source]
예시: /dualize-docs .local.claude/projects/{project-name}
/dualize-docs .local.claude/projects/{project-name} --archive-source
ls -ld <path> + test -w <path>.md 파일 1개 이상 존재: find <path> -name "*.md" -not -path "*/bot/*" -not -path "*/human/*" -not -path "*/archive/*" | head -1<path>/bot/ 또는 <path>/human/ 존재 시 AskUserQuestion:
승인 시 rm -rf <path>/bot <path>/human 후 진행.
--archive-source 플래그 시 추가 확인: "원본 .md 를 archive/YYYY-MM-DD/ 로 이동합니다. 진행할까요?"
find <path> -name "*.md" -not -path "*/bot/*" -not -path "*/human/*" -not -path "*/archive/*" | sort
목록과 줄 수 사용자에게 공유:
수집: N 파일, X 줄
Y줄 <path>/STATUS.md
...
서브에이전트 위임 금지. 모든 파일 순차 Read 후 mental model 에 확정:
파일 수 많으면 상위 개괄 파일(STATUS/README/INDEX)을 먼저, 이어서 나머지 그룹 순.
... 축약 금지human/insights.md 로)1M context 로 여러 문서 한꺼번에 봤기에 보이는 것들을 모읍니다. 원본 어떤 단일 문서에도 없는 내용입니다. 7 카테고리:
추출 규칙:
[메타인지] Pass 3 insights.md 작성 완료 직후 Adversarial Review 를 수행한다. 핵심 발견(모순, 숨어있는 것, 맹점, 향후 방향 P1) Top 3 각각에 대해:
- 근거 재점검: 여러 원본을 실제로 교차 대조한 결과인가, 단일 문서 해석인가? 인용 위치(
파일:섹션)가 실제로 해당 주장을 뒷받침하는가?- 전제 검증: 이 insight 가 성립하려면 어떤 전제가 필요한가? (예: "모순"은 두 문서가 실제로 같은 대상과 시점을 다룬다는 확인이 전제)
- 반대 증거 탐색: "내가 해석을 잘못 연결하지 않았나?" / "원본 저자가 이미 알고 있었나?" 같은 반박을 1개 이상 탐색.
[확신/추정/가설]태그가 실제 근거 강도와 일치하는지 재점검반박 유효 시 insight 강등(
[확신]을[추정]으로) 또는 섹션에서 제거, 부분 반박 시 "단, {가능성}" 인라인 추가.
| 성격 | bot 파일 후보 |
|---|---|
| 의사결정 기록 (시간순) | decisions-timeline.md |
| 구조와 흐름 | architecture.md |
| 구현 파일, 경로, 코드 레퍼런스 | implementation.md |
| API, 엔드포인트, 스키마 | api-contract.md |
| 외부 호출자 가이드 | caller-integration.md |
| 카탈로그와 인벤토리 | modules.md, screens-catalog.md 등 |
| 라이선스, 계약, 비용 | license-and-constraints.md |
| 외부 의사결정과 액션 | blockers.md |
| 운영 함정과 해결된 문제 | known-issues.md |
| 규칙, 금지, 컨벤션 | rules.md |
bot 파일 수는 주제 수에 따라 자연스럽게. 같은 주제를 두 파일로 쪼개거나 (과분할) 다른 주제를 한 파일에 섞지 (혼합) 않으면 됨. 작은 프로젝트는 3~5개, 큰 프로젝트는 10개 이상도 정상.
mkdir -p <path>/bot 후 생성.
---
title: 주제 제목
type: state-table | api-map | rule-set | decision-log | reference | catalog | known-issues | ...
last-updated: YYYY-MM-DD
source-files: [원본 상대 경로들]
---
> 진입점: [INDEX.md](./INDEX.md)경로/파일.확장자:시작[-끝] 완전 경로bot/INDEX.md (READ FIRST 라우팅)# bot/ (AI 에이전트 진입점)
> 이 디렉터리는 /dualize-docs 스킬로 YYYY-MM-DD 생성.
> 설명과 배경은 ../human/README.md, 메타 분석과 향후 방향은 ../human/insights.md 참조.
## 라우팅
| 파일 | 내용 | 갱신 |
|------|------|------|
| [decisions-timeline.md](./decisions-timeline.md) | ... | YYYY-MM-DD |
| ... | ... | ... |
human/README.md: 3단 구조 강제# {디렉터리 이름}
> 이 디렉터리는 "왜"를 담습니다. "무엇"은 [../bot/INDEX.md](../bot/INDEX.md), "그래서 어떻게"는 [insights.md](./insights.md) 참조.
## 1. 배경
## 2. 현재 상태
(요약 + **Mermaid 다이어그램 1개 이상**, README 에만 필수)
## 3. 남은 질문과 의사결정
## 더 읽을 거리
- [architecture.md](./architecture.md): ...
- [decisions.md](./decisions.md): ...
- [insights.md](./insights.md): 메타 분석, 개선점, 향후 방향
- [lessons.md](./lessons.md): ...
human/architecture.md: AS-IS vs TO-BE 다이어그램 중심human/decisions.md: 의사결정 타임라인 스토리라인human/lessons.md: 실패 사례와 교훈human/insights.md (아래 8.1)human/insights.md: Pass 3 산출# 인사이트: 메타 분석과 향후 방향
> 이 문서는 원본 N 파일을 한꺼번에 읽어서 드러난 것들입니다. 각 원본 단일 문서에는 없는 내용이라 **스킬이 1M context 로 추론한 것**이 섞여 있습니다. **[확신/추정/가설] 태그** 를 확인 후 사용자가 판단하세요.
> 사실은 [../bot/INDEX.md](../bot/INDEX.md), 배경과 의도는 [README.md](./README.md) 참조.
## 1. 발견된 모순과 부정합
- **[확신]** 근거: A.md:L34 vs B.md:L89. 같은 주제 다른 값. 갱신 누락으로 추정
- **[추정]** ...
## 2. 숨어있는 것 (잠재된 연결과 인과)
- **[가설]** C.md 의 X 와 D.md 의 Y 는 같은 이슈의 다른 증상일 가능성. 시기, 담당자, 키워드가 겹침. 두 문서를 개별로 읽을 때는 보이지 않음
- **[추정]** ...
## 3. 놓친 것 (미수행, 미검증)
- **[확신]** E.md 3절의 "Z 를 제이에게 확인" 액션. 이후 문서 어디에도 결과 기록 없음
- **[추정]** 회의 액션 #N, 완료 표시 없이 14일 경과
## 4. 맹점 (생각해본 적 없는 관점)
- **[가설]** 모든 원본에서 "X 동시성" 이 언급 안 됨. 배포 후 병목 가능
- **[가설]** ...
## 5. 아쉬운 점
- **[확신]** 회의록 포맷 제각각. 2개 회의가 서로 다른 템플릿. 통일 권장
- **[추정]** ...
## 6. 반복 패턴
- **[확신]** 여러 문서에서 "요구사항 철회 후 재작업" 패턴 2회. 구조적 교훈: 불확실 외부 의사결정 시 PoC 선행
- **[추정]** ...
## 7. 향후 방향 제안 (우선순위순)
1. **[P1]** 근거 + 왜 중요한지 + 구체 액션 + 예상 공수
2. **[P2]** ...
3. **[P3]** ...
## 8. 스킬이 판단 못 한 것
- X 근거를 원본에서 못 찾음. 도메인 전문가 확인 필요
- Y 는 문서화 안 됐지만 존재 가능. 코드 직접 확인 권장
해당 없는 섹션은 그 섹션 자체를 생략 (빈 헤더만 두지 말 것).
--archive-source 없으면 건너뜀. 있고 사용자 승인이면 하위 디렉터리 구조를 보존하며 archive 로 이동 (같은 파일명 충돌 방지):
TODAY=$(date +%Y-%m-%d)
mkdir -p <path>/archive/$TODAY
# 각 .md 파일을 원본 상대 경로 그대로 archive 아래에 재현
find <path> -maxdepth 3 -name "*.md" \
-not -path "*/bot/*" -not -path "*/human/*" -not -path "*/archive/*" \
| while read f; do
rel=${f#<path>/}
dest=<path>/archive/$TODAY/$rel
mkdir -p "$(dirname "$dest")"
mv "$f" "$dest"
done
이동 전 find <path> -type d 스냅샷을 archive/$TODAY/_ORIGINAL_TREE.txt 로 저장.
# bot 파일 줄 수
for f in <path>/bot/*.md; do
lines=$(wc -l < "$f")
[ $lines -gt 200 ] && echo "[WARN] 200줄 초과: $(basename $f) ($lines 줄)"
done
# human README mermaid 유무
grep -c '```mermaid' <path>/human/README.md
# 0 이면 경고
# human/insights.md 존재 필수
[ -f <path>/human/insights.md ] || echo "[WARN] insights.md 누락"
# insights.md 의 확신/추정/가설 태그 존재 확인
grep -cE '\*\*\[(확신|추정|가설)\]\*\*' <path>/human/insights.md
# 0 이면 경고 (근거 표시 누락)
# 코드 레퍼런스 축약(`...`) 검출
grep -nE '\.\.\..*\.(java|html|js|json|ts|py|xml|yml)' <path>/bot/*.md
# 매치 있으면 경고
# 코드 레퍼런스 유효성 샘플 5개
grep -rhEo '[A-Za-z0-9/._-]+\.(java|html|js|json):[0-9]+' <path>/bot/*.md \
| sort -u | head -5
# bot ↔ human 표 중복
for bf in <path>/bot/*.md; do
header=$(grep -m1 -E '^\| [^|]+ \| [^|]+ \|' "$bf" | head -c 60)
[ -z "$header" ] && continue
grep -l -F "$header" <path>/human/*.md 2>/dev/null \
&& echo "[WARN] $(basename $bf) 표가 human 에 등장"
done
AskUserQuestion 으로 체크포인트 강제:
AskUserQuestion:
question: "산출물 재읽기 완료. 다음 중 문제 발견되셨습니까?"
options:
- "없음 (리포트 진행)"
- "bot 내 누락, 중복 발견"
- "human 내 다이어그램, 설명 부족"
- "insights.md 의 근거 출처 부족"
- "코드 레퍼런스 불일치"
- "기타 (자유 서술)"
"없음" 아니면 해당 파일만 추가 수정 후 한 번 더 재읽기. 전체 재작성 금지 (무한 루프 방지).
재읽기 대상:
bot/INDEX.md 라우팅 테이블이 실제 파일만 가리키는가human/architecture.md 에 이식됐는가human/README.md 3단 구조 완전human/insights.md 각 항목에 [확신/추정/가설] 태그 + 근거 출처<path>/.dualize/source-map.json 자동 생성:
{
"generated-at": "2026-04-17T15:30:00Z",
"source-files": [
{"path": "STATUS.md", "lines": 183, "bytes": 9835},
{"path": "ANALYSIS.md", "lines": 908, "bytes": 56297},
...
],
"bot-files": {
"decisions-timeline.md": {
"source-files": ["ANALYSIS.md", "ARCHITECTURE.md", "meetings/2026-04-15-뷰어-데이터바인딩.md"],
"lines": 56
},
...
},
"human-files": {
"README.md": {"mermaid-count": 1, "lines": 66},
"architecture.md": {"mermaid-count": 3, "lines": 163},
"insights.md": {"confidence-tags": {"확신": N, "추정": N, "가설": N}, "lines": Z},
...
}
}
목적:
주의: .dualize/ 는 gitignore 후보. 사용자에게 "커밋할지 결정" 안내만.
[OK] dualize-docs 완료
대상: <path>
소스: N 파일 (X 줄)
- bot/ : M 파일 (Y 줄)
...
- human/ : K 파일 (Z 줄)
- README.md (Z줄, mermaid N)
- architecture.md (Z줄, mermaid N)
- decisions.md (Z줄)
- lessons.md (Z줄)
- **insights.md (Z줄, 확신 N / 추정 N / 가설 N)**
- .dualize/source-map.json 생성 (재실행 시 변경 추적용)
원본: {유지 | archive/YYYY-MM-DD/ 로 이동}
경고:
- (경고 있으면 나열)
주요 제안: insights.md 가 제안한 P1 액션 N건. 사용자가 판단과 반영 여부 결정
다음 단계:
- 에이전트 작업 시: <path>/bot/INDEX.md 부터 (사용자 CLAUDE.md "문서 탐색 우선순위" 원칙)
- 사람 리뷰 시: <path>/human/README.md 먼저, 이어서 <path>/human/insights.md 순
- 재실행: /dualize-docs <path>
.local.claude/, memory/, archive/ 자체가 인자면 경고 후 중단. .git/, node_modules/, target/ 경로 포함 시 사용자 확인 필수.rm -rf 와 mv 전 AskUserQuestion 확인 (3단계와 9단계). 무단 덮어쓰기 금지..md 한정: .html 등 비-MD 는 수집하지 않음. bot/, human/, archive/ 하위 제외.[확신/추정/가설] 태그 + 근거 출처 필수. 채택 여부는 사용자가 결정, 스킬은 플래그만 세움.... 축약 금지).공통 3블록(빈 / 부분 / 풀 데이터)은 CONTRACT 6-1절 참조.
[환경/규모] 원본 파일 총합 추정 토큰 ~600K+ (1M context의 60%, 한계 접근)
wc -l 합계로 대략 가늠)[데이터 결함] 원본 문서 간 내용 모순 감지
[모순] 태그로 양쪽 명시 + 해결 필요 항목을 별도 섹션으로 분리