메뉴
소스코드의 기능별 엔트리포인트와 호출 흐름을 .ai/60_codebase/에 색인하고, 도메인·계약·ADR 문서와 교차 참조를 연결합니다. 코드맵, code map, 코드 지도, 코드베이스 색인 시 사용합니다.
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
이슈 단위로 스펙, 실행 계획, 수행 요약을 관리하는 워크플로우입니다. 이슈 작업, 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 인덱스, 워크스페이스 안내판 작업 시 사용합니다.
SOC 직업 분류 기준
| 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의 호출 흐름 다이어그램 등)를 작성·갱신할 때 적용하는 규칙입니다.
.로 시작하는 항목도 같은 알파벳순 규칙으로 처리하며 별도 위치에 모아두지 않습니다.호출 흐름 다이어그램의 노드 순서는 의미적 흐름(엔트리포인트 → 핵심 로직 → 외부 의존성)이 우선이므로 이 규칙을 강제하지 않습니다. 단, 동일 레이어 내 동등한 형제 노드를 나열할 때는 위 규칙을 권장합니다.