code-map

개요

안내도가 선언한 SSoT(Single Source of Truth, 단일 진실 공급원)를 .ai/60_codebase/에 마크다운으로 색인합니다. SSoT가 소스 코드이면 기능별 엔트리포인트와 호출 흐름을, 원본 문서이면 ssot_dir 아래 문서 파일 지도를 만듭니다. AI가 구현, 테스트, 코드 리뷰, 문서 작업 등 맥락 파악이 필요할 때 60_codebase/index.md를 진입점으로 읽고, 관련된 SSoT·도메인 지식·계약·ADR 문서를 빠르게 찾을 수 있도록 합니다.

"건물·층" 비유의 2레이어 구조를 사용하며, 하나의 스킬이 두 가지 모드로 동작합니다:

• --local (floor 모드): 개별 리포의 .ai/60_codebase/에 코드 색인 또는 원본 문서 색인을 생성·관리
• --global (building 모드): 멀티 리포 환경에서 공통 도메인 지식을 통합·관리

관련 skill

• ai-workspace (권장): .ai/ 디렉토리 구조를 활용합니다. 없으면 .ai/60_codebase/ 디렉토리를 직접 생성합니다. .ai/30_contract/, .ai/40_domain/, .ai/50_adr/ 경로의 문서가 있으면 교차 참조로 연결합니다.
• context-harvest (쌍): 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/ — 모드 결정 후 해당 모드 파일만 읽습니다. --local은 SSoT 선언이 원본 문서이면 doc.md를, 그 밖이면 local.md를 읽습니다):
  • local.md — --local (floor 모드) 실행 절차 (SSoT가 소스 코드이거나 선언이 없을 때)
  • doc.md — --local (floor 모드) 원본 문서 색인 실행 절차 (SSoT 선언이 원본 문서일 때)
  • global.md — --global (building 모드) 실행 절차

사용법

/code-map --local          # 현재 리포의 코드 색인 또는 원본 문서 색인 생성/갱신
/code-map --global         # 멀티 리포 공통 도메인 지식 통합·관리

옵션을 생략하면 사용자에게 선택을 요청합니다.

---

적용 대상

• Java 웹 애플리케이션 (Spring Boot, Spring MVC 등)
• Java 배치 애플리케이션 (Spring Batch, 스케줄러 등)
• 원본 문서 저장소 (SSoT 선언이 원본 문서인 doc 프로파일 repo. ssot_dir 아래 문서 파일)

---

핵심 원칙

SSoT 원칙

• SSoT는 AI-CONTEXT.md 본문 2번째 줄(H1 제목과 그 뒤 빈 줄 제외)의 > SSoT: <값>. 선언을 따른다. 값은 소스 코드 또는 원본 문서이며 그 외 값은 선언으로 보지 않는다. 선언을 찾지 못하면 소스 코드를 SSoT로 본다. AI-CONTEXT.md는 있는데 선언을 찾지 못해 소스 코드로 진행하면 그 사실을 사용자에게 한 줄로 알리고, ai-workspace update로 선언을 보강할 수 있다고 안내한다. AI-CONTEXT.md가 없으면 알리지 않는다.
• .ai/60_codebase/의 문서는 SSoT에서 파생된 2차 산출물이다.
• SSoT와 문서 사이에 불일치가 발생하면 SSoT가 우선한다.