| name | ai-workspace |
| description | 프로젝트의 .ai 디렉토리 구조와 repo 안내도 AI-CONTEXT.md를 초기화하거나 최신 구조로 갱신합니다. dev(개발) 또는 doc(문서) 프로파일을 선택할 수 있습니다. 개별 repo의 층(floor)을 담당하며, 멀티 repo 워크스페이스 루트의 로비는 자매 스킬 ai-workspace-directory가 담당합니다. .ai 디렉토리, AI-CONTEXT.md 갱신, 안내도, workspace 초기화 시 사용합니다. |
개요
현재 프로젝트 루트에 .ai/ 디렉토리와 AI 협업을 위한 기본 구조를 생성하거나 갱신합니다.
이 스킬 디렉토리의 templates/ 아래 파일을 기준으로 구성합니다.
설계 원칙
- SSoT는 소스 코드. repo 안내도(
.ai/AI-CONTEXT.md)는 라우터일 뿐 진실의 원천이 아닙니다.
- 컨벤션 우선 (CoC). 멀티 repo는
<상위 워크스페이스>/<repo> 컨벤션으로만 지원합니다. 이 repo가 멀티 워크스페이스의 일부인지 단독 repo인지는 <repo>/../.ai/AI-CONTEXT.md 존재 여부로 자동 판정합니다 — 별도 메타 필드(building/lobby 등)는 두지 않습니다 (YAGNI). 컨벤션을 벗어난 구조는 지원하지 않습니다.
- 상위 워크스페이스와의 도메인 동기화. 멀티 워크스페이스의 일부인 경우 repo 안내도의
## 프로젝트 도메인 표(domain/keywords)는 상위 워크스페이스 안내도 Repos 표의 동일 path 행과 1:1 동기화됩니다 (ai-workspace-directory의 drift 메타 일치 검사 대상).
이 구조와 함께 사용 가능한 skill
- ai-workspace-directory (자매): 멀티 repo 워크스페이스 루트의 상위 안내도
.ai/AI-CONTEXT.md(로비) 생성·재구성. 상위 안내도의 Repos 표는 각 repo의 path/domain/keywords/status를 가지고, 본 스킬이 만드는 repo 안내도의 ## 프로젝트 도메인 표(domain/keywords)와 1:1 동기화 대상입니다.
- code-map: 소스코드 기능별 엔트리포인트·호출 흐름 색인 (
.ai/60_codebase/ 활용)
- git-commit: Conventional Commits 규칙에 따른 커밋 메시지 작성
- git-pr: PR 제목/메시지 작성 (비즈니스+테크 관점,
.ai/50_adr/, .ai/30_contract/, .ai/40_domain/ 활용)
- git-qa: 배포 대상 PR에서 repo별 QA 체크리스트 생성 (
.ai/99_workspace/ 활용)
- git-review: 비즈니스/테크 리뷰 수행 (
.ai/30_contract/, .ai/40_domain/ 활용)
- git-review-context: 리뷰 전 변경사항 사전 분석 (
.ai/99_workspace/ 활용)
- issue-work: 이슈 단위 스펙/계획/요약 관리 (
.ai/90_issues/ 활용)
사용법
/ai-workspace [dev|doc]
dev: 개발 프로젝트용 — 기술 스택, 코딩 컨벤션 섹션 포함doc: 문서 프로젝트용 — 기술 스택, 코딩 컨벤션 섹션 없음- 프로파일을 생략하면 사용자에게 선택을 요청합니다.
실행 절차
1단계: 프로파일 확인
$ARGUMENTS에서 프로파일을 읽습니다.
dev 또는 doc이면 그대로 사용합니다.- 값이 없거나 유효하지 않으면 사용자에게
dev / doc 중 선택을 요청합니다.
2단계: 모드 결정
.ai/ 디렉토리 존재 여부에 따라 모드를 결정합니다.
- 없음 → init 모드 실행
- 있음 → 사용자에게 선택 요청
init: 기존 .ai/를 완전히 덮어씁니다.update: 기존 내용을 최대한 보존하며 구조를 최신화합니다. → update 모드 실행
init 모드
init-0단계: 멀티/단독 repo 자동 판정 (CoC)
<repo>/..의 .ai/AI-CONTEXT.md 존재 여부로 자동 판정합니다. 사용자에게 묻지 않습니다 (컨벤션 우선).
[ -f ../.ai/AI-CONTEXT.md ] && echo "multi" || echo "solo"
| 결과 | 의미 | 이후 처리 |
|---|
multi | 멀티 워크스페이스의 일부 | init-2단계 보고에서 "상위 안내도: ../.ai/AI-CONTEXT.md" 안내. ## 프로젝트 도메인의 domain/keywords를 상위 안내도 Repos 행과 일치시키도록 사용자에게 권유. |
solo | 단독 repo | init-2단계 보고에서 "이 repo는 단독 repo입니다." 안내. ## 프로젝트 도메인은 단독 repo여도 유지 (에이전트 진입 단서). |
판정 결과는 사용자 보고에만 노출하고, AI-CONTEXT.md 본문에는 기재하지 않는다. 판정은 런타임에 매번 <repo>/../.ai/AI-CONTEXT.md 존재 여부로 자동 수행하므로, 안내도에는 판정 규칙만 둔다 (CoC). 정적 결과("이 repo는 단독/멀티다")를 git-tracked 안내도에 직접 기재하면, 클론 환경마다 부모 디렉토리 구조가 달라 거짓이 될 수 있다.
init-1단계: 파일 복사
이 스킬 파일의 위치(SKILL.md가 있는 디렉토리)를 기준으로 templates/ 경로를 찾아 복사합니다.
SKILL_DIR="<이 SKILL.md가 위치한 디렉토리>"
PROFILE="<선택된 프로파일: dev 또는 doc>"
cp -r "$SKILL_DIR/templates/shared/.ai/" .ai/
cp -r "$SKILL_DIR/templates/$PROFILE/.ai/"* .ai/
빈 디렉토리에는 .gitkeep 파일이 포함되어 있습니다 (templates에서 복사됨).
프로파일별 전용 파일 예시:
dev 전용: .ai/10_rules/architecture.md, .ai/10_rules/coding-convention.mddoc 전용: (없음)
last updated 치환
복사 직후 .ai/AI-CONTEXT.md의 첫 줄 > last updated: YYYY-MM-DD placeholder를 스킬 실행 시점의 시스템 날짜(date +%Y-%m-%d)로 치환합니다 (ai-workspace-directory와 동일 정책).
sed -i.bak "s/> last updated: YYYY-MM-DD/> last updated: $(date +%Y-%m-%d)/" .ai/AI-CONTEXT.md && rm .ai/AI-CONTEXT.md.bak
init-2단계: 완료 보고
생성된 파일 목록을 트리 구조로 출력하고, 사용자에게 다음 안내를 제공합니다.
- init-0단계 자동 판정 결과(
multi / solo) 요약. multi이면 상위 안내도 경로(../.ai/AI-CONTEXT.md)와 ## 프로젝트 도메인 동기화 안내, solo이면 단독 repo임을 명시.
.ai/AI-CONTEXT.md의 주석 처리된 섹션(<!-- ... -->)을 프로젝트에 맞게 채워주세요.## 프로젝트 도메인 표의 domain / keywords 두 행을 채워주세요 (단독 repo여도 유지). 멀티 워크스페이스인 경우 상위 안내도 Repos 표의 동일 path 행과 1:1 일치시켜야 합니다.- 이슈 작업 시
issue-work skill(/issue-work)을 사용하세요.
update 모드
기존 .ai/ 내용을 최대한 보존하면서 최신 구조로 맞춥니다.
update-1단계: 10_rules/ 정리
이전 버전에서 설치된 파일 중 개별 skill로 분리된 파일을 제거하고, 새 규칙 파일을 복사합니다.
사용자가 작성한 파일(architecture.md, coding-convention.md, file-change-policy.md)은 그대로 유지합니다.
rm -f .ai/10_rules/git-commit-policy.md
rm -f .ai/10_rules/git-pr-policy.md
rm -f .ai/10_rules/git-review-policy.md
rm -f .ai/10_rules/git-review-context-builder.md
rm -f .ai/10_rules/issue-workflow.md
cp "$SKILL_DIR/templates/shared/.ai/10_rules/context-loading.md" .ai/10_rules/context-loading.md
[ ! -f .ai/10_rules/file-change-policy.md ] && \
cp "$SKILL_DIR/templates/shared/.ai/10_rules/file-change-policy.md" .ai/10_rules/file-change-policy.md
if [ "$PROFILE" = "dev" ]; then
[ ! -f .ai/10_rules/architecture.md ] && \
cp "$SKILL_DIR/templates/dev/.ai/10_rules/architecture.md" .ai/10_rules/architecture.md
[ ! -f .ai/10_rules/coding-convention.md ] && \
cp "$SKILL_DIR/templates/dev/.ai/10_rules/coding-convention.md" .ai/10_rules/coding-convention.md
fi
update-2단계: 20_templates/ 정리
이전 버전에서 설치된 템플릿 파일(issue-work skill로 이관된 issue-*-template.md 등)을 제거합니다.
rm -rf .ai/20_templates/*
update-3단계: 콘텐츠 디렉토리 구조 정비
30_contract/, 40_domain/, 50_adr/, 60_codebase/, 90_issues/ 각각에 대해 아래를 수행합니다.
하위 디렉토리 구조 생성
정의된 하위 디렉토리가 없으면 생성합니다. 새로 생성한 빈 디렉토리에는 .gitkeep 파일을 함께 생성합니다.
| 디렉토리 | 생성할 하위 구조 |
|---|
30_contract/ | (하위 디렉토리 없음) |
40_domain/ | specs/, policies/common/, policies/local/ |
50_adr/ | active/, superseded/ |
60_codebase/ | (하위 디렉토리 없음) |
90_issues/ | active/, archive/ |
기존 파일 정리
각 디렉토리 바로 아래에 파일이 있으면 내용과 파일명을 분석하여 적절한 하위 디렉토리로 이동합니다.
이동 판단 기준:
| 디렉토리 | 판단 기준 |
|---|
40_domain/ | 파일명·내용이 기능 명세이면 specs/, 정책이면 policies/local/로 이동 |
40_domain/policies/ | policies/ 바로 아래에 파일이 있으면 policies/local/로 이동 |
50_adr/ | superseded, deprecated, replaced 등의 키워드가 있으면 superseded/, 아니면 active/로 이동 |
90_issues/ | 모든 Task 체크박스가 완료되었거나 완료 표시가 있으면 archive/, 아니면 active/로 이동 |
판단이 불가능한 파일은 해당 디렉토리 안에 legacy/를 만들어 이동합니다.
update-4단계: AI-CONTEXT.md 갱신
프로젝트를 분석하여 AI-CONTEXT.md를 갱신합니다. 이미 사용자가 작성한 섹션은 유지하고, 주석(<!-- ... -->)으로 비어있는 섹션만 채웁니다.
분석 대상:
- 프로젝트 루트의
README.md
- 디렉토리 구조 (
ls, find 등)
- 기존
.ai/AI-CONTEXT.md 내용
- 멀티/단독 자동 판정:
<repo>/../.ai/AI-CONTEXT.md 존재 여부 (CoC — 사용자에게 묻지 않음)
멱등 보강 검사 (신규)
기존 사용자 작성분은 보존하되, 아래 항목이 누락되어 있으면 표준 골격을 정확한 위치에 삽입합니다. 이미 있으면 사용자 작성분을 그대로 유지합니다.
| 항목 | 검사 | 누락 시 조치 |
|---|
본문 첫 줄 > last updated: YYYY-MM-DD | 본문 첫 줄이 > last updated: <ISO 날짜> 형식인가? | 누락이거나 형식 불일치이면 표준 형식으로 삽입·정정한다. 형식이 맞으면 매 update 실행 시 스킬 실행 시점의 시스템 날짜(date +%Y-%m-%d)로 갱신한다 (ai-workspace-directory와 동일 정책). |
| 본문 두 번째 줄 SSoT 선언 | > SSoT: 소스 코드. 이 파일은 안내도일 뿐 진실의 원천이 아니다. 존재? | 본문 첫 줄(> last updated: ...) 바로 아래에 표준 문구를 삽입한다. 비표준 문구이면 표준 문구로 교체한다. |
## 프로젝트 도메인 섹션 | 섹션 존재? | 헤더와 ## 프로젝트 목적 사이에 2행 표(domain / keywords)를 빈 값(<...>) 골격으로 삽입한다. domain/keywords는 사용자 입력을 요청하되, 멀티/단독 여부는 묻지 않는다 (CoC 자동 판정). |
## 디렉토리 구조의 .ai/ 한 줄 압축 | placeholder 주석에 .ai/는 한 줄로만 표시하라는 가이드가 있는가? 본문 트리에 .ai/ 하위가 2단계 이상 펼쳐져 있는가? | 가이드가 없으면 표준 주석으로 보강한다. 본문 트리에서 .ai/ 하위가 펼쳐져 있으면 한 줄(├── .ai/ # AI 협업 가이드 (상세는 ".ai 디렉토리 구조" 섹션))로 정렬을 권유한다. .ai/ 외 코드 트리 사용자 작성분은 보존한다. |
## 디렉토리 구조 트리 정렬 순서 | placeholder 주석에 IDE 정렬 순서 가이드가 있는가? 본문 트리가 같은 단계에서 대소문자 무시 알파벳순 + 디렉토리 우선 순서로 정렬되어 있는가? | 가이드가 없으면 표준 주석으로 보강한다(아래 디렉토리 트리 정렬 규칙 참고). 본문 트리가 어긋나 있으면 사용자에게 IDE 순서로 정렬할지 권유한다. 사용자 작성 주석·코멘트는 줄 단위로 매칭해 그대로 옮긴다. |
## 에이전트 운영 지침 섹션 + 전제 컨벤션 한 줄 | 섹션과 "전제: 상위 디렉토리에 .ai/AI-CONTEXT.md가 있으면 ..." 한 줄이 존재? | ## .ai 디렉토리 구조 바로 다음에 표준 골격(전제 한 줄 + ### 진입 절차 3단계 + ### 작성 규칙)을 삽입한다. 사용자가 별도 운영 지침을 추가했다면 그 아래에 보존한다. |
구버전 ## 워크스페이스 위치(4행 표) → ## 프로젝트 도메인(2행 표) 마이그레이션 | 구버전 섹션이 존재? | 섹션명을 ## 프로젝트 도메인으로 변경하고, building / lobby 행을 삭제한 뒤 domain / keywords 두 행만 유지한다 (CoC로 흡수된 메타 필드 제거). |
구버전 구조 마이그레이션
구버전 AI-CONTEXT.md("AI가 작업 시 지켜야 할 원칙"·"코딩 컨벤션"·"프로젝트 규칙"이 별도 섹션으로 분리된 형태)를 발견한 경우에만 references/legacy-migration.md를 읽고 그 절차를 따릅니다.
일회성 마이그레이션 로직입니다. 운영 중인 프로젝트가 모두 신버전으로 전환 완료되면 이 소섹션과 참조 파일을 제거해도 됩니다.
update-5단계: 완료 보고
변경된 내용을 요약하여 보고합니다.
- 새로 생성된 디렉토리/파일 목록
- 이동된 파일 목록 (이동 전 → 이동 후)
legacy/로 이동된 파일이 있으면 사용자에게 수동 분류를 요청합니다.
디렉토리 트리 정렬 규칙
.ai/AI-CONTEXT.md의 ## 디렉토리 구조 트리(사용자가 채우는 프로젝트 루트 트리)를 작성·갱신할 때 적용하는 규칙입니다. init 모드의 보고 트리 출력과 update 모드의 멱등 보강 검사가 모두 이 규칙을 따릅니다.
- 같은 단계 내 정렬 기준: 대소문자를 무시한 알파벳순으로 정렬합니다.
- 디렉토리 우선: 디렉토리를 동일 단계의 파일보다 위에 둡니다.
- 숨김 항목 위치 고정 금지:
.로 시작하는 항목(예: .ai/, .gitignore)도 같은 알파벳순 규칙으로 처리하며 별도 위치(맨 위/맨 아래)에 모아두지 않습니다.
- 결과: IntelliJ·VS Code 등 IDE의 기본 표시 순서와 일치합니다.
## .ai 디렉토리 구조 섹션의 트리(10_rules/, 20_templates/, …)는 숫자 prefix가 정렬 키로 작동하므로 위 규칙과 자연스럽게 정합합니다.
