Documentation Manager (문서 관리자)
인간과 AI 에이전트를 위한 살아있는 프로젝트 지식. 코드는 방법과 주장의 진위 여부에 대한 진실의 원천입니다.
AGENTS.md + docs/ 는 무엇을, 왜, 결정 사항 및 계획을 기록하지만, 코드와 충돌할 경우 코드를 절대 재정의하지 않습니다.
핵심 규칙
AGENTS.md를 허브로 선호합니다.agents.md가 이미 존재하면 그것을 사용합니다.CLAUDE.md만 존재하면, 문서 인덱스로 확장하거나AGENTS.md를 추가하고 상호 링크를 겁니다. 세 개의 경쟁 허브를 만들지 마십시오.- 생성/업데이트된 모든 문서는 상대 Markdown 링크를 사용하여 허브 및 관련 문서로 연결됩니다.
- 이유 없이 지속적인 지식을 삭제하지 마십시오. ADR에는 '다음으로 대체됨' 메모를 선호합니다.
- 자동 커밋 또는 자동 푸시를 하지 마십시오. Git 작업은 사용자에게 맡깁니다.
- 생성된 콘텐츠는 사용자의 언어(또는 저장소의 주 언어)로 작성합니다. 이 스킬 본문은 생태계 호환성을 위해 영어로 작성되었습니다.
- 양보다 정확성과 유용성을 선호합니다. 핵심 세트를 먼저 작성하고, 선택적 문서는 요청 시 작성합니다.
- 의도 우선(프로젝트 수준). 의도(Intent) 를 분류합니다:
integrate(통합) |audit(감사) |from-zero(처음부터) (및 선택적 혼합). 0단계를 참조하십시오. 순수 기능/계획/동기화에는 필수 아님. - 충돌 시 코드가 승리합니다. 구조적 검증에 실패한 문서 주장은 '모순됨(Contradicted)/누락됨(Missing)'으로 표시됩니다. 문서에 맞추기 위해 코드를 작성하지 말고 문서를 수정하거나 플래그를 지정하십시오.
- 통합 우선(의도=integrate인 경우). 성숙한 문서 → 인덱스 + 격차 + 정식 링크; 제품 비전/요구사항/ADR을 병렬로 재작성하지 마십시오. adopt-integrate를 참조하십시오.
- 주제당 하나의 권위. 각 주제에는 하나의 정식 문서가 있으며, 다른 모든 문서는 이에 링크됩니다.
- 채택/from-zero 프로젝트의 적용 범위 매트릭스. 제품 표면(네비게이션, ModuleId, 패키지)이 문서화됨/링크됨/격차로 나타납니다.
- 기능 원자성. 하나의 슬러그(Slug) ≈ 하나의 ModuleId 또는 경계 컨텍스트. 클러스터 = 인덱스 + 하위 항목.
- 상태 분류법. references/status-taxonomy.md 참조.
- 샌드박스 옵트인 / 일급 from-zero. 사용자가 요청할 때(
test/등)Out: sandbox:path를 출력합니다. 샌드박스 허브 배너는 비-SSOT + 승격 계획을 표시합니다. - 기능 오토파일럿 (v1.5 / v2). 일반적인 "새 기능 X" / "documentá X" → 스킬이 계획과 기능 팩 중에서 선택하고, 기본 비-쓰기(non-writes) 를 적용하며, 종류(Kind) (신규 기능 | 스파이크 | 에픽 | 재설계)를 설정합니다. 구현 브릿지 (배치 / 스텁)는 옵트인("implementá", "stubs", "scaffold") 시에만 적용되며, 기본값은 문서 전용 + 한 줄 힌트입니다. modes.md §3 및 implementation-bridge.md를 참조하십시오.
- 계획 모드 (v1.3+). 그린필드 기능 아이디어는 가짜 구현 팩이나 전체 프로젝트 부트스트랩이 아닌
docs/plans/<slug>/에 배치합니다. 코드가 실제로 존재할 때(스텁만 있는 것이 아닐 때)docs/features/<slug>/로 승격합니다. - ArkGate 브릿지 (v1.4). ArkGate가 감지되면(
ark.config.json,ark-check,.ark/, ark 스킬) 또는 사용자가 방금 게이트를 완료한 경우, 브릿지 하위 흐름을 실행합니다: 계약에서 인벤토리 보강; 게이트 통과 후 → 범위 지정 동기화 / 감사; 잔여 위반 → 주장을 '모순됨(Contradicted)/일부(Partial)'로 표시 — 잘못된 아키텍처를 변명하기 위해 문서를 재작성하지 마십시오. Ark 없음 → 작동 없음. 구현 브릿지의 배치 힌트는 감지 시 Ark 레이어를 재사용합니다. arkgate-bridge.md 및 modes.md §9 참조. - 지식 대시보드 (v1.6). 계획/기능/주장의 선택적 정적 HTML 뷰(
scripts/generate-docs-dashboard.sh→docs/audit/generated/dashboard.html). Markdown이 SSOT이며, HTML은 gitignored된 읽기 전용 뷰입니다. 감사 후 한 번 또는 "dashboard" 요청 시 제공합니다. knowledge-dashboard.md 및 modes.md §10 참조. - 스킬 강화 (v1.7). 유지 관리자: 릴리스 전에
validate-skill.sh+test-skill-hardening.sh를 실행합니다. 에이전트: skill-discovery.md를 통해 설치/버전을 감지하고, 오래된 경우 재설치를 제안합니다(무음 자동 패치 금지). - v2.0 패키지. 10배 라인을 완성합니다: 기능 1.4–1.7 및 docs/adoption-matrix.md 추적. 기준 설치 바닥은 2.0.0으로 유지됩니다. 다국어 2.1.0; 모노레포 2.2.0; 팀 2.3.0; 브릿지 완료 2.4.0; 현재 라인은 2.5.0+ (지식 OS 100배를 향한 첫 번째 증분 — 살아있는 주장 + CI 감사, 두 번째 10배가 아님).
- 다국어 스택 감지 (v2.1 슬라이스 A / 스킬 2.1.0). 프로젝트 발견 시(통합/감사/처음부터/채택), skill-discovery.md의 다국어 스택 감지(또는
scripts/detect-stack.sh)를 통해 파일 시스템(package.json,pyproject.toml,go.mod, …)에서 스택을 감지합니다. 스택별 인벤토리 및 스택별 문서 레이아웃 지침을 사용합니다. Node/TS를 가정하지 마십시오. 코드 증거 없이 프레임워크에 대한 ModuleId/엔드포인트를 절대 발명하지 마십시오. modes.md §0.3 참조. - 모노레포 허브 (v2.2 슬라이스 B). skill-discovery.md의 모노레포 허브(또는
scripts/detect-packages.sh)를 통해 다중 패키지 트리(pnpm-workspace.yaml,package.json작업 공간,go.work, 다중 패키지 디렉토리)를 감지합니다. 루트 허브는 덤프가 아닌 맵 + 패키지 인덱스입니다. 다중 패키지 적용 범위는 격차 패키지를 표시합니다. 루트만 인덱싱할 때 기본 패키지 비-쓰기가 적용됩니다. modes.md §0.4 참조. - 팀 거버넌스 (v2.3 슬라이스 C). 선택적
docs/team/과 소유자 + 승인 노트(마지막 승인 스타일)를 포함합니다. team-governance.md에 따라 생성 또는 링크합니다. 허브는 HR 위키가 되지 않고 팀에 링크합니다. 통합 우선 — 팀 추가는 제품 비전/요구사항/ADR을 재작성해서는 안 됩니다. CODEOWNERS 엔진이나 BPM이 없습니다. modes.md §11 참조. - 템플릿 텔레메트리 (v2.4 슬라이스 D). 템플릿/스킬 UX 격차 전용 옵트인 로컬 원장 (template-telemetry.md;
scripts/template-telemetry.sh). 기본적으로 꺼져 있음; 소스/비밀/저장소 URL을 절대 보내지 않음; 네트워크 절대 사용 안 함; 옵트인이 꺼져 있으면 에어갭에서 작동 안 함. modes.md §12 참조. - 살아있는 주장 + CI 구조 감사 (v2.5 / 지식 OS 첫 번째 증분). 감사 매트릭스는 살아있는 주장 v0을 사용합니다:
anchor.path/ 선택적anchor.symbol/ 선택적anchor.hash,severity(critical|normal), 평결은 변경되지 않음. 매트릭스 우선 (audit-template.md); 절차 living-claims.md; 연결 ADR-0001. 진실 점수는 조언적(대시보드 휴리스틱)으로 유지됩니다. 로컬 에어갭scripts/audit-claims.sh/ 예시docs-auditCI가 게이트(중요 모순 시 실패)입니다. SaaS 없음. modes.md §6 / §13 참조.
0단계 — 범위, 모드 및 의도 감지
범위(Scope) (필수):
| 범위 | 시기 | 출력 초점 |
|---|---|---|
| project | 전체 제품 / "프로젝트 문서" | 허브 + 프로젝트 문서 (의도에 따라) |
| feature | 코드가 있는(또는 갱신 팩의) 명명된 기능/모듈 | docs/features/<slug>/ + 허브 링크 |
| plan | 코드 이전 또는 없는 명명된 새 기능/에픽 | docs/plans/<slug>/ + 허브 링크 |
| hybrid | 아직 허브가 없는 경우 기능/계획 | 팩 또는 계획 + 최소 허브 |
모드(Mode) (필수):
| 모드 | 신호 |
|---|---|
| bootstrap | 그린필드, 허브/문서 없음, 또는 비어/얇은 상태에서 from-zero 의도 |
| adopt | 코드는 존재; 문서가 얇거나 없거나 integrate 의도 |
| audit | "문서 감사", "문서 vs 코드", 드리프트, 주장 검증 |
| plan | "새 기능", "계획", "에픽", "vamos a construir X" (코드 없음) |
| feature | 코드가 있는(또는 될) 하나의 기능/모듈 문서화 |
| sync | 변경 사항에 대한 Diff/PR/문서 업데이트; Ark가 방금 통과한 포스트게이트 |
| roadmap | 릴리스/에픽 목록 갱신 계획 |
의도(Intent) (프로젝트 수준 작업에만 필수):
| 의도 | 사용자 신호 (예시) | 행동 |
|---|---|---|
| integrate | "문서 개선", "정리", "허브 동기화", 성숙한 개선 | adopt-integrate (또는 얇으면 전체); 드리프트 의심 시 선택적 사전 감사 |
| audit | "감사", "문서가 거짓말하나?", "문서 vs 코드", "경로 검증" | 코드 인벤토리 + 주장 매트릭스 전용 (또는 핸드오프) |
| from-zero | "완전히 새로", "처음부터", "test/에 문서 생성", "폴더 X에 전체 KB" | 전체 지식 베이스; 경로가 주어지면 샌드박스 선호; 코드에서 추론; 오래된 문서는 가설로만 처리 |
추론(질문을 과도하게 하지 마십시오):
- "nueva feature X" / "new feature X" / "quiero agregar X" → 기능 오토파일럿 (코드 없으면 계획, 코드 있으면 기능; 표현에서 종류 결정). 의도 = 해당 없음
- "implementá X" / "generá stubs" / "scaffold X" → 필요한 경우 오토파일럿 A단계 + 구현 브릿지 옵트인 (스텁이 요청된 경우에만 코드)
- "generá toda la documentación en
test/" → 의도: from-zero | Out: sandbox:test/ - 성숙한 저장소 + "mejorá / integrá / indexá" → 의도: integrate
- "auditar docs" / "código vs docs" → 의도: audit
- 모호한 프로젝트 작업에 기존
docs/가 있는 경우 → 한 번만 질문: integrate | audit | from-zero - 명명된 단일 표면 → 사용자에게 비-쓰기를 나열하거나 폴더를 선택하도록 절대 요구하지 마십시오
- "after ark-check" / "post-gate docs" / 게이트가 방금 실행됨 + 문서 의도 → 동기화 또는 ArkGate 브릿지를 사용한 감사
- "dashboard" / "docs HTML" / "knowledge report" → 지식 대시보드 생성 (knowledge-dashboard.md)
- "owners" / "quién es dueño" / "team docs" / "approval notes" / "docs/team" → 팀 거버넌스 (team-governance.md; modes §11)
- "template telemetry" / "opt-in telemetry" / "record template gap" → 사용자가 옵트인하는 경우에만 템플릿 텔레메트리 (template-telemetry.md; modes §12); 기본값 꺼짐
- "living claims" / "truth score" / "docs CI" / "fail on Contradicted" → 살아있는 주장 + 로컬 CI 게이트 (living-claims.md; modes §13)
성숙도(Maturity) (관련 시): thin(얇음) | mixed(혼합) | mature(성숙) — modes.md 참조.
추론 후에도 범위/모드가 여전히 모호하면 한 번 질문합니다. references/modes.md에서 절차를 로드합니다.
쓰기 전에 공지:
Scope: <x> | Mode: <y> | Intent: <integrate|audit|from-zero|n/a> | Variant: <full|integrate|arkgate-bridge|n/a> | Maturity: <…|n/a> | Out: <root|sandbox:path> | Stack: <node-ts|python|go|mixed|unknown|n/a> | Monorepo: <yes|no|n/a> | ArkGate: <none|detected> | Slug: <slug|n/a>
integrate 시 비-쓰기를 나열하십시오 (모노레포 루트 인덱스 전용일 경우 패키지 비-쓰기 포함). audit 시 매트릭스 경로와 주요 모순을 나열하십시오. from-zero + 샌드박스 시 승격 계획을 포함하십시오. plan 또는 feature 시 경로 + 기본 비-쓰기를 나열하십시오. ArkGate 브릿지 시 신호와 포스트게이트 동기화 대 감사 보강을 나열하십시오. 프로젝트 수준 시 발견된 Stack 및 Monorepo를 포함하십시오.
권장 레이아웃
project-root/
├── AGENTS.md
└── docs/
├── product-vision.md # bootstrap / from-zero / adopt-full
├── requirements.md
├── architecture.md
├── roadmap.md
├── team/ # v2.3 팀 거버넌스 (선택 사항)
│ ├── OWNERS.md
│ └── approval-notes.md
├── audit/ # 의도 audit (선택 사항)
│ └── claims-matrix.md # 살아있는 주장 v0 열
├── adr/ # 패키지 / 프로젝트 ADR (선택 사항)
├── plans/<slug>/ # v1.3 계획 모드 (코드 이전 / 에픽)
│ └── README.md
├── decisions/
└── features/<slug>/ # 코드 기반 기능 팩
지원 문서는 정당한 경우에만 추가하십시오 (from-zero는 전체 최소 핵심 세트를 생성할 수 있음).
산출물 매트릭스 (요약)
| 산출물 | from-zero / bootstrap | integrate (성숙) | audit | plan | feature | sync |
|---|---|---|---|---|---|---|
| 허브 | 생성 | 확장 / 인덱싱 | 선택적 상태 업데이트 | 계획 링크 | 링크 | 필요 시 |
| 핵심 서사 문서 | 예 | 재작성 금지 | 아니요 (읽기 전용) | 아니요 | 아니요 | 영향 시 |
| 적용 범위 매트릭스 | 예 | 필수 | 인벤토리의 일부 | 선택적 행 | 행 | 업데이트 |
| 주장 매트릭스 | 선택적 사전 | 드리프트 시 권장 | 필수 | 해당 없음 | 감사 시 범위 지정 | 드리프트 시 |
계획 docs/plans/ | 해당 없음 | 해당 없음 | 해당 없음 | 필수 | 존재 시 링크 | 영향 시 |
| 기능 팩 | 주요 도메인 | 격차 / 항목 | 아니요 (요청 없음) | 아니요 (승격까지) | 필수 | 영향 시 |
팀 docs/team/ | 소유자 알려진 경우 | 요청 시 생성/링크 | 아니요 | 해당 없음 | 해당 없음 | 영향 시 |
| 병렬 전체 트리 | 샌드박스 허용 | 루트에서 금지 | 해당 없음 | 해당 없음 | 해당 없음 | 해당 없음 |
워크플로우 (모든 모드)
- 0단계 — 범위, 모드, 의도(프로젝트인 경우), 성숙도/변형, Out, 슬러그; 관련 시 ArkGate 신호 감지; 프로젝트 작업을 위해 스택 및 모노레포 감지 (skill-discovery.md 다국어 + 모노레포 허브).
- 먼저 코드 발견 — 스택 인식 인벤토리; 모노레포인 경우 패키지 인덱스 + 패키지별 인벤토리; 트리, 매니페스트, 진입점, 샘플 테스트. 그런 다음 문서(있는 경우). 명명된 기능의 경우 해당 표면을 먼저 검색합니다. Ark가 감지되면 arkgate-bridge.md에 따라 인벤토리를 보강합니다.
- 감사이거나 문서가 존재하고 의도가 integrate/from-zero이며 드리프트가 의심되는 경우: 조정(reconciliation) 실행 (modes.md § 감사, audit-template.md). 포스트게이트 → 브릿지 핸드오프 (modes.md §9).
- 파일 계획 — 생성/업데이트 및 비-쓰기(기능/계획의 기본값)를 포함합니다.
- 쓰기 — 콘텐츠를 작성합니다.
- 구조적 검증 — 확인 가능한 주장을 평가합니다.
- 커버리지 및 주장 매트릭스 업데이트 — 살아있는 주장 형식을 사용합니다(v2.5+).
- 상태 및 링크 유효성 확인 — (깨진 링크 없음, superseded by 메모).
- 텔레메트리 — 옵트인된 경우 template-telemetry.md에 따라 격차를 기록합니다.
- 마침 — 예: "완료되었습니다. 업데이트: ..., 비-쓰기: x/y/z."