القائمة
소스코드의 기능별 엔트리포인트와 호출 흐름을 .ai/60_codebase/에 색인하고, 도메인·계약·ADR 문서와 교차 참조를 연결합니다. 코드맵, code map, 코드 지도, 코드베이스 색인 시 사용합니다.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
이슈 단위로 스펙, 실행 계획, 수행 요약을 관리하는 워크플로우입니다. 이슈 작업, issue, 이슈 시작, 이슈 완료, 워크플로우 복구(--workflow-only), 이어하기, resume, 작업 재개(--resume), 이슈 정리, 작업공간 정리, 정리(--clear), audit 리포트 검토·피드백 후 승인 보정(--response) 시 사용합니다.
현재 스킬 repo의 skill을 선택하여 Claude Code·Agents·Antigravity·Codex·Junie 경로(~/.claude/skills/ 등 5개)에 설치합니다. --all(전체 경로)·--clear(클린 재설치)·--self(self-install 부트스트랩) 옵션을 지원합니다. skill 설치, install skills, 스킬 배포, 스킬 재설치, self-install 시 사용합니다.
이슈 스펙 대비 구현 완료 여부를 독립 감사인 관점에서 검증합니다. 이슈 감사, issue audit, 구현 검증, 크로스체크 시 사용합니다.
대화 중 중요한 맥락(배경, 결정, 미결 사항, 다음 액션)을 `.ai/99_workspace/notes/` 아래 마크다운 파일로 저장합니다. 맥락 저장, context save, 임시 저장, 논의 스냅샷, 작업 메모 시 사용합니다.
PR 제목과 메시지를 정책(Conventional Commits 제목 + 이슈별 비즈니스/테크 관점)에 맞게 작성합니다. PR 작성, PR 메시지·설명 작성, pull request, 풀리퀘스트, PR 올리기 전 정리, 리뷰어용 설명 정리 시 사용합니다. 실제 PR 생성·제출이 아니라 메시지 텍스트 작성용입니다.
멀티 repo 워크스페이스 루트의 로비 `.ai/AI-CONTEXT.md`를 생성하거나 진단·재구성합니다. `ai-workspace`의 자매 스킬로, building 안내판(=lobby) 역할의 lean 라우터를 만듭니다. 로비, lobby, AI-CONTEXT.md, building 인덱스, 워크스페이스 안내판 작업 시 사용합니다.
| name | code-map |
| description | 소스코드의 기능별 엔트리포인트와 호출 흐름을 .ai/60_codebase/에 색인하고, 도메인·계약·ADR 문서와 교차 참조를 연결합니다. 코드맵, code map, 코드 지도, 코드베이스 색인 시 사용합니다. |
소스코드를 SSoT(Single Source of Truth, 단일 진실 공급원)로 삼아, 기능별 엔트리포인트와 호출 흐름을 .ai/60_codebase/에 마크다운으로 색인합니다.
AI가 구현, 테스트, 코드 리뷰 등 코드베이스의 맥락 파악이 필요할 때 60_codebase/index.md를 진입점으로 읽고, 관련된 소스코드·도메인 지식·계약·ADR 문서를 빠르게 찾을 수 있도록 합니다.
"건물-층" 비유의 2레이어 구조를 사용하며, 하나의 스킬이 두 가지 모드로 동작합니다:
--local (floor 모드): 개별 리포의 .ai/60_codebase/에 코드 색인을 생성·관리--global (building 모드): 멀티 리포 환경에서 공통 도메인 지식을 통합·관리.ai/ 디렉토리 구조를 활용합니다. 없으면 .ai/60_codebase/ 디렉토리를 직접 생성합니다. .ai/30_contract/, .ai/40_domain/, .ai/50_adr/ 경로의 문서가 있으면 교차 참조로 연결합니다.code-map이 소스코드(How)를 색인하는 스킬이라면, context-harvest는 소스코드 바깥의 What+Why를 수집·증류하여 30_contract/, 40_domain/, 50_adr/ 문서를 생성하는 스킬입니다. context-harvest 실행 후 code-map --local sync를 실행하면 새로 생긴 문서를 교차 참조로 연결합니다..ai/10_rules/context-loading.md — 있으면 따르며, 이미 적재되어 있으면 재로딩하지 않습니다..ai/30_contract/index.md, .ai/40_domain/index.md, .ai/50_adr/index.md — 교차 참조 연결용 (index 먼저 → 관련 파일만 선택적으로 추가 로드)references/ — 모드 결정 후 해당 모드 파일만 읽습니다):
/code-map --local # 현재 리포의 코드 색인 생성/갱신
/code-map --global # 멀티 리포 공통 도메인 지식 통합·관리
옵션을 생략하면 사용자에게 선택을 요청합니다.
.ai/60_codebase/의 문서는 소스코드에서 파생된 2차 산출물이다.각 코드맵 문서는 3개 레이어로 구성한다:
| 레이어 | 내용 | 생성 주체 |
|---|---|---|
| What | 이 코드/모듈이 무엇인가 (엔티티 정의, 데이터 모델, API 계약) | 에이전트가 소스코드에서 자동 추출 |
| How | 어떻게 동작하는가 (호출 흐름, 의존성, 설정) | 에이전트가 소스코드 + 설정파일에서 자동 추출 |
| Why | 왜 이렇게 설계했는가 (비즈니스 판단, 아키텍처 결정, 규제 근거) | 반드시 사람이 태깅 |
.ai/ 내 관련 문서(계약, 도메인 명세, ADR 등)가 있으면 Why에 교차 참조 링크로 연결한다.[WHY-NEEDED] 태그로 표시하여 사람에게 요청한다.Why 절의 참조 계층:
.ai/ 내부 문서 (30_contract, 40_domain, 50_adr).ai/ 내부 문서 안에 원본 출처로 기재한다..ai/ 내부 문서가 아직 없으면 [DOC-NEEDED] 태그로 표시한다.60_codebase/는 소스코드에서 .ai/ 내 다른 디렉토리로의 네비게이션 허브 역할을 한다:
.ai/
├── 30_contract/ # 소프트웨어 계약 (API 명세, 연동 규약)
├── 40_domain/ # 비즈니스 도메인 (기능 명세, 정책, 용어)
├── 50_adr/ # 의사결정 기록
└── 60_codebase/ # ← 이 스킬의 작업 대상
├── index.md # 기능별 엔트리포인트 색인 (진입점)
└── <feature>/ # 기능별 디렉토리
└── <action>-call-flow.md # 엔트리포인트별 상세 호출 흐름
코드맵 문서에서 관련 문서를 교차 참조 링크로 연결한다:
../30_contract/<문서>.md../40_domain/specs/<문서>.md../40_domain/policies/common/<문서>.md 또는 ../40_domain/policies/local/<문서>.md../50_adr/active/<ADR>.md모드를 결정한 뒤, 해당 모드의 참조 파일만 읽고 그 절차를 따른다.
| 모드 | 참조 파일 | 요약 |
|---|---|---|
--local (floor) | references/local.md | 개별 리포의 코드 색인 생성/갱신/점검 (build / sync / check / rebuild) |
--global (building) | references/global.md | repository.yaml 기반 멀티 리포 수집 → 아키텍처 문서·건물 안내도 생성/갱신/점검 |
--local (개별 리포) --global (문서 전용 리포)
┌────────────────────┐ ┌──────────────────────────────────┐
│ .ai/60_codebase/ │←──── 읽기 ─────│ .ai/10_rules/ │
│ index.md │ │ architecture.md ← 생성 │
│ <feature>/ │ │ service-call-flows.md ← 생성 │
│ .ai/30_contract/ │ │ infra.md ← 생성 │
│ .ai/40_domain/ │ │ .ai/60_codebase/ │
│ .ai/50_adr/ │ │ repository.yaml │
└────────────────────┘ │ index.md ← 생성 │
└──────────────────────────────────┘
60_codebase/index.md와 교차 참조 문서를 읽어서 아키텍처 문서와 안내도를 생성.ai/10_rules/architecture.md(+선택적 분리 문서)와 .ai/60_codebase/index.md이다이 스킬은 최초 생성(build) 이후 3가지 트리거로 지속 업데이트된다:
--local sync를 실행--global에서 새 리포를 등록할 때도 수동 트리거각 색인 문서에 다음 메타데이터를 YAML frontmatter로 관리한다:
---
last_synced: 2026-04-08 # 마지막 동기화 일시
source_hash: a1b2c3d # 마지막 동기화 시점의 커밋 해시 (어디까지 반영했는지의 참조)
status: current | stale | draft # 문서 상태
---
source_hash는 "이 색인이 어느 시점의 소스코드까지 반영했는가"를 나타내는 참조이다.source_hash 이후 변경된 파일 목록을 기준으로 판정한다. 무관한 파일만 변경된 경우 stale로 판정하지 않는다.[UPDATE-NEEDED] 태그로 리포팅한다.| 태그 | 의미 | 생성 위치 |
|---|---|---|
[WHY-NEEDED] | Why 레이어가 미태깅 — 사람의 입력 필요 | local 색인 문서 |
[DOC-NEEDED] | 관련 문서(contract/domain/ADR)가 존재해야 하나 미작성 | local 색인 문서 |
[UPDATE-NEEDED] | 소스 변경 후 색인 미반영 | local check |
[NOT-INDEXED] | --local 미실행 리포 — 동기화 대상에서 제외 | global 리포 목록 |
[REPO-NOT-FOUND] | 로컬에 clone이 없는 리포 | global 리포 목록 |
--local로 최초 build--global 적용.ai/60_codebase/ 내부 트리(index.md의 파일 구조 다이어그램, <feature>/<action>-call-flow.md의 호출 흐름 다이어그램 등)를 작성·갱신할 때 적용하는 규칙입니다.
.로 시작하는 항목도 같은 알파벳순 규칙으로 처리하며 별도 위치에 모아두지 않습니다.호출 흐름 다이어그램의 노드 순서는 의미적 흐름(엔트리포인트 → 핵심 로직 → 외부 의존성)이 우선이므로 이 규칙을 강제하지 않습니다. 단, 동일 레이어 내 동등한 형제 노드를 나열할 때는 위 규칙을 권장합니다.