| name | ai-workspace-directory |
| description | 멀티 repo 워크스페이스 루트의 로비 `.ai/AI-CONTEXT.md`를 생성하거나 진단·재구성합니다. `ai-workspace`의 자매 스킬로, building 안내판(=lobby) 역할의 lean 라우터를 만듭니다. 로비, lobby, AI-CONTEXT.md, building 인덱스, 워크스페이스 안내판 작업 시 사용합니다. |
개요
멀티 repo가 한 워크스페이스 아래 모여있는 환경에서, 워크스페이스 루트의 로비 .ai/AI-CONTEXT.md 를 생성하거나 진단·재구성하는 스킬입니다.
ai-workspace(floor 측, 각 repo의 .ai/ 전체 구조 담당)의 자매 스킬이며, 빌딩의 안내판(directory) 역할을 합니다. 로비는 floor 안내도를 가리키는 메타 라우터일 뿐 도메인 콘텐츠를 보유하지 않습니다.
산출물의 본질
- 포함: 라우팅·색인 (어디로 가야 할지 알려주는 안내판)
- 금지: 도메인 지식 본문, 코드 스니펫, floor 상세 목차 — 이건 floor의 책임
파일 경로 규약
| 대상 | 경로 | 담당 스킬 |
|---|
| 로비 (building 안내판) | <워크스페이스 루트>/.ai/AI-CONTEXT.md | 이 스킬 |
| floor 안내도 (층별 안내도) | <워크스페이스 루트>/<repo>/.ai/AI-CONTEXT.md | ai-workspace |
규약: 모든 AI-CONTEXT.md는 각자의 .ai/ 디렉토리 안에 있습니다. 프로젝트 루트에 직접 배치하지 않습니다.
대전제 (절대 위배 금지)
- 소스 코드가 무조건 SSoT다.
- markdown은 코드를 가리키는 지도이지 코드의 사본이 아니다.
- 로비는 라우터지 콘텐츠가 아니다. 도메인 지식 본문은 로비에 들어가지 않는다.
- 정보 충돌 시 우선순위: 소스 코드 > 각 repo 안내도 > 이 안내도(상위 워크스페이스).
- 설계 원칙: 컨벤션 우선 (CoC). 멀티 repo는
<상위 워크스페이스>/<repo> 컨벤션으로만 지원한다. 각 repo가 어느 상위 워크스페이스에 속하는지는 <repo>/../.ai/AI-CONTEXT.md 존재로 자동 판정하며, repo 측 안내도에 역참조 메타 필드(building/lobby 등)를 두지 않는다 (YAGNI). 컨벤션을 벗어난 구조는 지원하지 않는다.
관련 skill
ai-workspace (자매): 각 floor의 .ai/ 전체 구조와 floor 안내도 <repo>/.ai/AI-CONTEXT.md를 생성·갱신합니다. 이 스킬은 그 위에서 building 안내판 역할을 하는 로비를 다룹니다.- 양방향 도메인 동기화:
ai-workspace-directory는 로비의 Repos 표에 각 repo의 path/domain/keywords/status를 적고, ai-workspace는 각 repo의 안내도 ## 프로젝트 도메인 표에 동일한 domain/keywords를 적습니다. 두 값은 1:1 동기화 대상입니다 (update 모드의 drift 메타 일치 검사가 이를 점검). 역참조(repo → 상위 워크스페이스)는 별도 메타 필드 없이 CoC(<repo>/../.ai/AI-CONTEXT.md 존재 자동 판정)로 처리합니다.
참조 문서
- 공통 규칙:
.ai/10_rules/context-loading.md — 있으면 따르며, 이미 적재되어 있으면 재로딩하지 않습니다.
- 스킬 고유 추가 참조:
- 현재 워크스페이스 루트의 기존
.ai/AI-CONTEXT.md (있을 경우 — update 모드 입력)
- 각 floor의
<repo>/.ai/AI-CONTEXT.md (디스크 스캔으로 존재 여부만 확인 — status 판정용)
- 분리 참조 파일 (
references/ — 해당 단계에 도달했을 때만 읽습니다):
사용법
/ai-workspace-directory [init|update]
init: 새 로비 .ai/AI-CONTEXT.md를 작성합니다.update: 기존 로비를 진단·재구성하고 floor 이동 목록을 산출합니다.- 모드를 생략하면 워크스페이스 루트의
.ai/AI-CONTEXT.md 존재 여부로 자동 판정합니다 (없으면 init, 있으면 update).
워크스페이스 루트가 git 저장소가 아니어도 동작합니다 (git 명령에 의존하지 않음).
실행 절차
1단계: 모드 결정
사용자가 모드를 명시했으면 그대로 진행합니다. 미지정 시 워크스페이스 루트의 .ai/AI-CONTEXT.md 존재 여부로 자동 분기합니다.
자동 판정 규칙
<루트>/.ai/AI-CONTEXT.md | 자동 선택 모드 |
|---|
| 부재 | init |
| 존재 | update |
판정 대상 경로는 워크스페이스 루트의 .ai/ 안입니다. 프로젝트 루트의 ./AI-CONTEXT.md는 검사 대상이 아닙니다 (파일 경로 규약 위반이므로 발견 시 사용자에게 이전을 안내).
사용자 확인 절차 (덮어쓰기 위험 회피)
자동 판정 결과를 사용자에게 명시하고 확인을 받습니다. 확인 없이는 다음 단계로 진행하지 않습니다.
init 자동 선택 시: "<루트>/.ai/AI-CONTEXT.md가 없습니다. init 모드로 새 로비를 작성할까요?"update 자동 선택 시: "기존 <루트>/.ai/AI-CONTEXT.md (N줄, last updated: YYYY-MM-DD)를 update 모드로 진단·재구성할까요?"
사용자가 자동 선택과 다른 모드를 원할 경우:
| 자동 선택 | 사용자 요청 | 처리 |
|---|
init | update | 기존 파일이 다른 경로(예: 프로젝트 루트, 다른 워크스페이스)에 있을 가능성을 안내하고 경로 재확인 요청 |
update | init | 기존 파일을 덮어쓰게 됨을 명시하고 한 번 더 확인 요청. 백업이 필요하면 사용자에게 수동 백업을 안내한 후 진행 |
비-VCS 환경 안전성
워크스페이스 루트는 일반적으로 VCS 대상이 아닌 로컬 환경 파일입니다. 이 스킬은 다음 원칙을 따릅니다.
- git 명령에 의존하지 않습니다.
git log, git status, git rev-parse 등 어떤 git 호출도 하지 않으며, 워크스페이스 루트가 git 저장소가 아니어도 동일하게 동작합니다.
- 모드 자동 판정은 파일 존재 여부만으로 결정합니다 (
test -f).
- 본문 첫 줄
> last updated: YYYY-MM-DD는 스킬 실행 시점의 시스템 날짜(date +%Y-%m-%d)로 자동 기록합니다. git 커밋 시각·작성자 정보는 사용하지 않습니다.
update 모드에서도 재구성 본문을 작성할 때 last updated를 매번 시스템 날짜로 갱신합니다.
init 모드
새 로비 .ai/AI-CONTEXT.md를 작성합니다.
init-1단계: 입력 수집
다음 정보를 사용자에게 받습니다. (입력 예시는 examples.md의 init 모드 예시 참조)
| 항목 | 필수/선택 | 설명 |
|---|
| building 이름 | 필수 | 워크스페이스/조직 이름 (예: "ACME 워크스페이스") |
| building 정체성 (2~3문장) | 필수 | 이 building이 무엇을 위한 곳인지 |
| floor 목록 | 필수 | 각 floor의 path(상대 경로), domain(맡은 영역), keywords(라우팅 키워드) |
| archived floor 목록 | 선택 | 사용자가 명시적으로 "더 이상 작업하지 않음"으로 표시할 floor의 path |
floor 목록은 사용자가 한 번에 모두 제공하지 않을 수 있습니다. 누락 시 항목별로 대화형 질의로 수집합니다.
init-2단계: 디스크 스캔 — floor status 결정
입력된 각 floor에 대해 다음 규칙으로 status를 결정합니다.
| 조건 | status |
|---|
사용자가 archived로 명시 | archived |
<루트>/<path>/.ai/AI-CONTEXT.md 존재 | active |
<루트>/<path>/.ai/AI-CONTEXT.md 부재 | placeholder |
placeholder로 판정된 floor에 대해 결과 보고 시 명시적 경고를 함께 출력합니다.
[경고] floor <path>에 안내도가 없습니다. 해당 floor에서 ai-workspace 스킬을 실행해 안내도를 생성하는 것을 권장합니다.
archived floor는 디스크 존재 여부와 무관하게 archived로 고정되며, 향후 update 모드의 drift 검사 대상에서도 제외됩니다.
init-3단계: .ai/ 디렉토리 준비
<루트>/.ai/ 디렉토리가 없으면 생성합니다. git 명령에 의존하지 않습니다.
init-4단계: .ai/AI-CONTEXT.md 작성
standard-structure.md를 읽고, 그 필수 규칙과 골격에 따라 <루트>/.ai/AI-CONTEXT.md를 작성합니다. 산출물 형식 규칙은 해당 문서가 단일 출처입니다.
init-5단계: 분량 가드레일 검증
생성된 파일의 줄 수를 측정해 가드레일을 검증합니다.
| 범위 | 판정 | 조치 |
|---|
| 150~250줄 | 정상 | — |
| 250줄 초과 | 비대 | 어떤 섹션이 큰지 분석해 사용자에게 보고. 도메인 본문 또는 floor 상세 목차가 섞여 있는지 점검 |
| 150줄 미만 | 짧음 | floor 수가 적은 경우 정상. 정체성·라우팅·운영 지침이 빈약하면 보강 권장 |
분량 검증은 권고이며 실패 시에도 파일 생성은 진행합니다. 다만 250줄 초과는 SSoT 위배 가능성이 높으므로 사용자에게 명시적 확인을 요청합니다.
init-6단계: 보고
다음 정보를 사용자에게 출력합니다.
- 생성된 파일 경로 (
<루트>/.ai/AI-CONTEXT.md)
status별 floor 수 (active X개 / placeholder Y개 / archived Z개)placeholder floor 목록과 경고 메시지- 분량 가드레일 결과
update 모드
기존 로비 .ai/AI-CONTEXT.md를 입력으로 받아 진단 → 재구성 → 이동 목록 3단계를 순서대로 출력합니다.
이 모드는 파일을 덮어쓰기 전 사용자 확인을 반드시 받습니다. 진단·이동 목록만 출력하고 실제 갱신은 사용자 승인 후에만 수행합니다.
update-0단계: 입력 수집 (사전)
- 기존
<루트>/.ai/AI-CONTEXT.md를 읽습니다. 파일이 없으면 사용자에게 init 모드로 전환할지 확인합니다.
- 디스크 스캔: 워크스페이스 루트의 모든 1차 자식 디렉토리에 대해
<루트>/<dir>/.ai/AI-CONTEXT.md 존재 여부를 수집합니다.
- 기존 로비
Repos 표(구버전은 Floors)에서 archived로 표시된 repo 목록을 추출합니다 (drift 검사 제외 대상).
update-1단계: 진단 리포트 출력
다음 4개 카테고리를 순서대로 점검하고 마크다운 리포트로 출력합니다. 리포트 형식은 examples.md의 update-1단계 출력 형식 템플릿을 따릅니다.
(1) SSoT 위배 패턴 진단
ssot-checklist.md의 각 항목을 점검합니다. 위배가 있으면 발견 위치(섹션·라인 범위)와 발췌를 기록합니다.
(2) 로비 역할 위배 진단
로비는 라우터일 뿐이므로 다음을 점검합니다.
| 패턴 | 설명 |
|---|
| 도메인 본문 | 결제·인증 등 특정 도메인의 본문 설명이 로비에 포함됨 |
| 코드 스니펫 | 함수·클래스·설정 등 코드 조각이 로비에 포함됨 |
| floor 상세 목차 | 특정 floor의 파일 트리·디렉토리 구조가 로비에 펼쳐져 있음 |
| 정책 본문 중복 | floor의 .ai/10_rules/·40_domain/policies/에 있어야 할 정책 본문이 로비에 중복됨 |
| 비대 | 산출물이 250줄을 초과 |
(3) drift 진단 (로비 ↔ 디스크)
다음 두 방향으로 차이를 점검합니다. archived repo는 양방향 모두 검사에서 제외합니다.
| 방향 | 판정 | 조치 |
|---|
| 로비에 있음 + 디스크에 안내도 있음 | 정상 | active 유지 |
| 로비에 있음 + 디스크에 안내도 없음 | drift | placeholder로 전환 + 안내도 생성 권장 |
| 로비에 없음 + 디스크에 안내도 있음 | drift | 로비 Repos에 등록 필요 |
| 로비에 있음 + 디스크 디렉토리 자체 없음 | drift | 사용자에게 repo 삭제/이전/archive 여부 확인 |
(3-보강) 메타 일치 검사 (조건부)
각 repo 안내도(<repo>/.ai/AI-CONTEXT.md)의 ## 프로젝트 도메인 메타 블록이 존재할 때만 동작합니다 (ai-workspace 보강 결과로 자기 선언 메타가 들어있는 경우). 메타 블록이 없으면 검사를 스킵합니다.
| 검사 항목 | 위배 판정 | 조치 |
|---|
로비 Repos.<path> 행의 domain 과 repo 자기 선언 domain 일치 | 다르면 drift | update-3단계 meta-mismatch 카테고리로 정렬 권고 (어느 쪽이 SSoT에 가까운지 사용자 확인 — 통상 repo 자기 선언이 더 가깝다고 권고) |
로비 Repos.<path> 행의 keywords ⊇ repo 자기 선언 keywords 핵심 셋 | 빠진 키워드가 있으면 drift | 로비 keywords에 누락 키워드 추가 권고 |
스킵 fallback: repo 측 메타 블록이 없으면 다음 안내만 출력합니다 — "해당 repo 안내도(<path>/.ai/AI-CONTEXT.md)에 ## 프로젝트 도메인 메타 블록이 없습니다. ai-workspace update로 보강을 권장합니다."
역참조(repo → 상위 워크스페이스) 일치 검사는 CoC 도입으로 수행하지 않습니다 — 메타 필드 자체가 없으므로 검사 대상이 아닙니다 (../.ai/AI-CONTEXT.md 존재로 자동 판정).
(4) 형식 위배
형식 기준은 standard-structure.md를 따릅니다.
| 검사 | 위배 시 조치 |
|---|
본문 첫 줄이 > last updated: YYYY-MM-DD인가 | update-2단계에서 자동 갱신 |
본문 두 번째 줄이 > SSoT: 소스 코드. 이 파일은 라우터일 뿐 진실의 원천이 아니다. 인가 | update-2단계에서 표준 문구로 자동 삽입·교체 (비표준 문구이면 표준 문구로 치환) |
| YAML frontmatter가 없는가 | 있다면 update-2단계에서 제거 |
| 표준 6개 H2 섹션이 모두 있고 순서가 맞는가 | update-2단계에서 보강·재정렬 |
Repos 섹션명을 사용하는가 (구버전 Floors 아님) | 구버전 Floors → Repos로 섹션명 정규화 |
Repos 테이블이 정확히 4열(path/domain/keywords/status)인가 | update-2단계에서 정규화 |
에이전트 운영 지침에 ### 진입 절차 4단계가 있는가 | update-2단계에서 표준 진입 절차 4단계 삽입. 사용자가 커스텀 단계를 추가했다면 보존하되 표준 4단계 누락 시 보충 |
status 값이 active/placeholder/archived 중 하나인가 | 다른 값은 사용자 확인 후 정규화 |
update-2단계: 재구성된 로비 .ai/AI-CONTEXT.md 전문 출력
standard-structure.md의 표준 섹션 구조를 따라 재구성된 전문을 코드 블록으로 출력합니다. 출력 형식은 examples.md의 update-2단계 출력 형식 템플릿을 따릅니다.
재구성 규칙:
- 본문 첫 줄
> last updated:를 스킬 실행 시점의 시스템 날짜로 갱신합니다.
- 본문 두 번째 줄 SSoT 선언(
> SSoT: 소스 코드. 이 파일은 라우터일 뿐 진실의 원천이 아니다.)이 없으면 표준 문구로 삽입합니다. 비표준 문구이면 표준 문구로 교체합니다.
- YAML frontmatter가 있으면 제거합니다.
- 6개 H2 섹션을 표준 순서로 정렬합니다. 누락 섹션은 빈 본문 + 안내 주석으로 생성합니다.
- 구버전
## Floors 섹션명이 있으면 ## Repos로 정규화합니다.
Repos 테이블을 4열로 정규화하고 drift 진단 결과에 따라 status를 갱신합니다.에이전트 운영 지침 섹션이 비어 있거나 ### 진입 절차 4단계가 없으면 표준 골격(번호 4단계 + ### 작성 규칙 글머리)을 삽입합니다. 사용자가 추가한 운영 지침 항목은 ### 작성 규칙 아래 또는 별도 서브헤딩으로 보존합니다 (소실 금지).- 진단에서 발견된 도메인 본문·코드 스니펫·repo 상세 목차·정책 본문 중복은 본문에서 제거하고 update-3단계 이동 목록으로 옮깁니다.
- 사용자가 작성한 라우팅 규칙·정체성 문구는 본문 형태로 살리되, SSoT 위배 패턴은 제거합니다.
파일 쓰기 규칙:
- 출력 후 사용자에게 명시적으로 확인을 요청합니다: "이대로
<루트>/.ai/AI-CONTEXT.md에 덮어쓸까요?"
- 사용자가 승인하면 파일에 기록하고, 분량 가드레일(150~250줄)을 init 모드와 동일하게 검증합니다.
- 사용자가 거절하면 파일을 변경하지 않고 진단 리포트와 재구성 전문만 출력 상태로 남깁니다.
update-3단계: floor 이동 후보 목록 출력
진단에서 발견된 "로비에 있어서는 안 되는" 콘텐츠를 후속 스킬이 입력으로 받기 좋은 YAML 구조로 출력합니다. 출력 YAML 형식은 examples.md의 update-3단계 출력 형식 템플릿을 따릅니다.
필수 필드:
| 필드 | 설명 |
|---|
content_id | 항목 고유 식별자 (예: lobby-overflow-001) |
target_floor | 대상 repo의 path (로비 Repos 표의 path와 일치) |
target_location_hint | 대상 floor 내부의 추정 경로 (예: <repo>/.ai/40_domain/specs/payment-domain.md). 사용자/후속 스킬이 최종 결정하므로 어디까지나 힌트 |
category | domain-content / code-snippet / repo-toc / policy-duplicate / meta-mismatch / other |
confidence | high / medium / low — target_floor 추정의 자신도 |
reason | 왜 이동 대상인지 한 줄 근거 |
source_location | 원본 로비에서의 위치 (예: lines 45-78) |
excerpt | 원본 발췌 (전문 또는 요약 — 후속 스킬이 적용할 수 있을 만큼 충분히) |
target_floor 추정 규칙:
- 발췌의 도메인 키워드를 로비
Repos 표의 각 repo keywords와 매칭.
- 키워드 다수 일치 →
high, 단어 부분 일치 → medium, 일치 없음 → low + target_floor: unknown.
archived floor는 추정 대상에서 제외.
이 출력은 화면에 표시만 하고 파일을 직접 수정하지 않습니다. 후속 스킬(또는 사용자 수작업)이 이 YAML을 입력으로 받아 각 floor에 콘텐츠를 배치합니다.
update-4단계: 보고
- 1·2·3단계 출력의 위치(또는 사용자에게 제시한 영역)를 정리합니다.
- 파일 변경 여부: 사용자 승인 시
<루트>/.ai/AI-CONTEXT.md 갱신됨, 거절 시 변경 없음.
- 분량 가드레일 결과 (
init 모드와 동일 기준).
- drift로 인해
placeholder로 전환된 floor 목록과 안내도 생성 권장 메시지.
- 이동 후보 개수 및
target_floor: unknown 항목 수 (사용자 후속 확인 필요).
