5장

ai-workspace-standards 소개

7장에서 살펴볼 "개발 도구 + variant" 모델을 실제로 구현한 저장소가 ai-workspace-standards다. 이 장에서는 이 저장소가 정확히 무엇이고, 어떤 파일들로 구성되어 있으며, 어떤 프로젝트 템플릿들을 제공하는지 차근차근 소개한다.

출처: ai-workspace-standards (GitHub), ADR-0031 L1–L2 Fork Model, CONSTITUTION.md §0 SSOT Architecture

이 장에서 다루는 것

ai-workspace-standards가 무엇이고, 왜 "워크스페이스 루트"로 클론해야 하는지
저장소 전체 디렉터리 구조와, 세션이 실제로 어떤 순서로 파일을 읽고 실행하는지(런타임 흐름)
CONSTITUTION.md, CLAUDE.md, GEMINI.md, CODEX.md, AGENTS.md 다섯 핵심 파일의 역할
templates/ 아래에 있는 13개 variant 각각이 어떤 도메인을 위한 것인지
세션 시작 체크리스트와 new-project.ts 스캐폴딩 흐름의 개념적 그림

저장소가 무엇인가

ai-workspace-standards는 스스로를 "Vibe Coding과 Harness Engineering을 위한 멀티 에이전트 팀 운영방안"이라고 소개한다. 여러 AI 코딩 도구(Claude Code/App, Antigravity CLI/Desktop 등)에 걸쳐 동일한 동작·워크플로우·품질 기준을 적용하기 위한 저장소다.

이 저장소를 쓰는 방식이 조금 독특하다. 보통의 라이브러리처럼 프로젝트 하나에 종속시키는 게 아니라, 저장소 자체를 워크스페이스의 루트로 클론해서 쓴다. Windows에서는 C:\git, macOS/Linux에서는 ~/git 같은 위치가 그 예다. 이렇게 해두면 그 아래에서 새로 만드는 모든 프로젝트가 워크스페이스의 공유 규칙을 자동으로 물려받는다.

ai-workspace-standards는 "완성된 프로젝트"가 아니라 "프로젝트를 만드는 방법"을 배포하는 저장소다. — 워크스페이스 루트로 클론하는 이유

전체 아키텍처 한눈에 보기

이후 절에서 5대 핵심 파일, variant, L0→L1→L2를 하나씩 뜯어보기 전에, 이 조각들이 실제로 저장소 안 어디에 어떤 이름으로 앉아 있는지부터 통째로 보고 시작하는 게 방향을 잃지 않는 데 도움이 된다. 워크스페이스 루트를 클론하면 아래와 같은 최상위 구조가 나온다.

C:\git\  (워크스페이스 루트 = L0)
├── CONSTITUTION.md          ← §2: 무엇을 지켜야 하는가 (마스터 표준, L0 원본)
├── CLAUDE.md                ← §2: Claude Code/App에서 어떻게 실행하는가
├── GEMINI.md                ← §2: Antigravity CLI/Desktop에서 어떻게 실행하는가
├── CODEX.md                 ← §2: Codex CLI/Desktop App에서 어떻게 실행하는가
├── AGENTS.md                ← §2: 누가 그 일을 하는가 (에이전트 로스터, L0 원본)
├── agents/                  ← §5: pm.md 등 에이전트 정의 원본 (L0, 여기서만 편집)
│   └── pm.md
├── .claude/                 ← §2: Claude 전용 커맨드·스킬 (/sync, create-variant 등)
├── .gemini/                 ← §2: Gemini/Antigravity 전용 커맨드·스킬 (같은 이름, 다른 구현)
├── .codex/                  ← §2: Codex 전용 프롬프트·스킬·설정
├── .agents/                 ← §2: 도구-불가지론적 커맨드·스킬 (AGENTS.md 표준 지원 도구용)
├── scripts/                 ← §4·§5: new-project.ts, propagate-to-templates.ts 등 운영 스크립트
├── templates/                (L1 + 공식 L2)
│   ├── common/              ← §5: L1 — L0 스냅샷, variant 생성 시 출발점
│   │   └── agents/pm.md     ← extends: ../../../agents/pm.md (L0 참조 + 워크스페이스 전용 섹션 제거)
│   ├── co-develop/          ← §3: L2 공식 variant (소프트웨어 개발, 6단계)
│   ├── co-design/           ← §3: L2 공식 variant (UI/UX, 5단계)
│   ├── co-work/             ← §3: L2 공식 variant (협업/문서, 6단계)
│   ├── co-security/         ← §3: L2 공식 variant (레드팀, 6단계)
│   ├── co-consult/          ← §3: L2 공식 variant (컨설팅, 7단계)
│   ├── co-deck/   [beta]    ← §3: L2 공식 variant (강의/발표, 11단계)
│   ├── co-game/             ← §3: L2 공식 variant (게임 개발)
│   ├── co-export/ [beta]    ← §3: L2 공식 variant (수출입 무역 컨설팅)
│   ├── co-hr/     [beta]    ← §3: L2 공식 variant (HR/노동 컴플라이언스)
│   ├── co-news/   [beta]    ← §3: L2 공식 variant (금융/경제 저널리즘)
│   ├── co-price/  [beta]    ← §3: L2 공식 variant (가격 관리/컨설팅 시뮬레이터)
│   ├── co-safety/ [beta]    ← §3: L2 공식 variant (EHS/GxP 컴플라이언스 플랫폼)
│   ├── co-abap/             ← §3: L2 공식 variant (SAP ABAP 개발)
├── Projects/                 (L3 — new-project.ts로 스캐폴딩된 라이브 프로젝트 작업 디렉토리)
│   └── <my-project>/
│       ├── docs/context.md  ← §4: 이 프로젝트의 설정 문서 (variant의 빈 골격을 채운 것)
│       ├── agents/          ← variant에서 상속받아 이 프로젝트 전용으로 계속 진화
│       └── (독립된 git 저장소 — 워크스페이스 루트와 별개)
└── memory/
    └── YYYY-MM-DD.md            ← §4: 세션 간 이어지는 컨텍스트 기록

이 트리에서 눈여겨볼 것은 네 가지 층이 실제 디렉터리 구조로 그대로 드러난다는 점이다. 루트 바로 아래(CONSTITUTION.md·CLAUDE.md·GEMINI.md·CODEX.md·AGENTS.md·agents/·scripts/)가 L0이고, templates/common/이 L1이며, templates/co-*/가 L2, 실제 개발자가 작업하는 프로젝트 작업 디렉토리인 Projects/*/가 L3다. 즉 "L0→L1→L2→L3"는 추상적인 개념도가 아니라, 클론한 폴더를 ls 한 번만 쳐도 바로 눈에 보이는 물리적 배치다.

이 구조 위에서 실제로 일이 진행되는 순서(런타임 흐름)는 다음과 같다.

세션 시작. 에이전트가 CONSTITUTION.md → 현재 프로젝트의 docs/context.md(프로젝트 설정) → AGENTS.md(에이전트 로스터) → memory/YYYY-MM-DD.md 순서로 읽는다(§4에서 다룸).
도구별 실행 규칙 적용. Claude Code/App이면 CLAUDE.md와 .claude/, Gemini/Antigravity 계열이면 GEMINI.md와 .gemini/, Codex이면 CODEX.md와 .codex/가 세부 실행 방식을 정한다.
새 프로젝트가 필요하면. scripts/new-project.ts가 templates/co-<variant>/(L2)의 전체 구성을 Projects/<name>/로 복제해 L3 프로젝트 작업 디렉토리를 만든다. 이때 templates/co-<variant>/ 자신은 한 세대 앞서 templates/common/(L1)에서 스냅샷을 받아 만들어진 상태였다.
운영 중 L0가 바뀌면. scripts/propagate-to-templates.ts가 /sync 파이프라인의 일부로 L0의 변경을 L1(templates/common/)에 자동·지속적으로 발행한다. 이미 태어난 L2나 L3에는 자동으로 전파되지 않는다. 이것은 8장에서 다루는 "포크" 원칙이다.

한 문장으로: L0는 "루트 바로 아래", L1은 "templates/common/", L2는 "templates/co-*/", L3는 "Projects/*/, 즉 실제 프로젝트 작업 디렉토리" — 이 네 좌표만 기억하면 이후 절의 모든 설명을 실제 폴더 위치에 맞춰 따라갈 수 있다.

핵심 파일 다섯 가지

워크스페이스 루트에는 모든 프로젝트가 공통으로 참조하는 다섯 개의 핵심 파일이 있다.

CONSTITUTION.md는 마스터 공유 표준으로, 세션을 시작할 때 가장 먼저 읽어야 하는 문서다. 워크스페이스 전체의 거버넌스 규칙, PR 워크플로우, 멀티 에이전트 아키텍처 원칙이 여기에 정의되어 있다. CLAUDE.md는 Claude Code/App에서의 구체적 동작 방식(훅, 슬래시 커맨드, 에이전트 디스패치 규칙)을 담고, GEMINI.md는 Gemini/Antigravity CLI/Desktop에서의 동등한 동작을 정의하며, CODEX.md는 Codex CLI/Desktop App에서 같은 표준을 순차 역할 전환과 프롬프트 기반 실행으로 적용하는 방법을 정의한다. AGENTS.md는 워크스페이스 전체에서 사용 가능한 에이전트들의 정본 목록(roster) 역할을 한다. 이 파일명은 2장에서 소개한, Claude Code를 비롯한 30개 이상의 도구가 공통으로 읽는 개방형 AGENTS.md 표준과 같다. 다만 이 저장소에서는 "에이전트 레지스트리 및 오케스트레이션 레퍼런스"라는 더 구체적인 역할까지 겸한다. 파일 맨 위에 "이 파일은 AI 도구를 향한 지시문이 아니라 사람이 정의한 여러 역할의 등록부"라고 명시해 둘 정도다.

이 네 파일의 관계를 한 문장으로 요약하면, CONSTITUTION.md가 "무엇을 지켜야 하는가"를 정의하고 CLAUDE.md/GEMINI.md/CODEX.md는 "그것을 각 플랫폼에서 어떻게 실행하는가"를, AGENTS.md는 "누가 그 일을 하는가"를 정의한다.

AGENTS.md의 에이전트 항목은 다음과 같은 필드로 구성된다. 구체적인 작성 가이드와 도구별 구현 매핑은 8장 §3 AGENTS.md 심화에서 다룬다.

필드	의미	필수	예시
`## Agent: {이름}`	에이전트 식별자	필수	`## Agent: reviewer`
`역할`	이 에이전트가 무엇을 하는가	필수	"텍스트 파일의 오탈자를 검토한다"
`입력`	어떤 입력을 받는가	권장	"검토 대상 텍스트 파일 경로"
`출력`	어떤 출력을 내는가	권장	"오탈자·허점·개선점 목록"
`권한`	파일 접근 범위	권장	"읽기 전용" / "쓰기 허용 — 지정된 파일에만"
`handoff_to`	완료 후 넘길 대상	선택	`handoff_to: reviewer`

구체적인 규칙 하나를 예로 이 관계를 따라가 보자. "PR 제목과 본문은 반드시 영어로 쓴다"는 규칙이 있다고 하면, 이 규칙 자체는 CONSTITUTION.md에 한 번만 적힌다. CLAUDE.md는 이 규칙을 Claude Code에서 어떻게 강제할지를 정의한다. 예를 들어 /sync 커맨드의 언어 게이트(language-guard.ts)가 커밋 전에 이 규칙을 자동 검사하도록 명시하는 식이다. GEMINI.md는 같은 규칙을 Gemini/Antigravity 쪽 파이프라인에서 강제하는 방법을 정의하고, CODEX.md는 Codex 세션이 동일한 규칙을 프롬프트와 수동 게이트로 실행하는 방식을 정의한다. 그리고 이 검사를 실제로 수행하는 것이 "누구"인지, 즉 어떤 에이전트가 이 게이트를 담당하는지는 AGENTS.md의 로스터에 등록돼 있다. 규칙 하나가 다섯 파일에 각자 다른 각도로 나타나는 셈이다. 이것은 중복이 아니라 "무엇을 · 어떻게 · 누가"라는 세 질문에 대한 서로 다른 답이다.

다섯 파일 아래에는 실행 가능한 자산을 담는 폴더가 있다. 커맨드·스킬·프롬프트는 네 곳에 나뉘어 있는데, .claude/는 Claude Code/App 전용, .gemini/는 Gemini/Antigravity CLI/Desktop 전용, .codex/는 Codex CLI/Desktop App 전용, 그리고 .agents/는 어느 한 도구에 묶이지 않는 도구-불가지론적(engine-agnostic) 커맨드·스킬을 담는다. 예를 들어 /sync·/meeting 같은 커맨드나 create-variant·audit-workspace 같은 스킬은 플랫폼별 표면에 같은 이름으로 존재하되, 각자 자기 플랫폼의 도구 규칙(Claude Code의 Agent 도구 문법, Antigravity의 서브에이전트 방식, Codex의 프롬프트/순차 역할 전환 방식 등)에 맞춰 구현이 조금씩 다르다. AGENTS.md 표준을 지원하는 외부 도구(Codex, Cursor 등)는 공통 규칙과 .agents/ 자산을 함께 참조할 수 있다.

templates와 variant 13종

templates/ 디렉터리는 버전이 관리되는 프로젝트 템플릿 "variant"들의 모음이다. 각 베리언트(variant)는 특정 도메인을 위한 완결된 멀티 에이전트팀 구성을 담고 있다. PM, 전문 에이전트들, 단계별 거버넌스 파이프라인이 여기에 포함된다. 저장소가 제공하는 베리언트(variant)는 다음과 같다.

co-develop소프트웨어 개발용. PM·Architect·Designer·Code Writer·Test Runner·Security Monitor로 구성된 6단계 거버넌스 파이프라인.

co-designUI/UX용. Design Lead·UX Researcher·Visual Designer·Prototype Engineer 등 5단계 반복 워크플로우.

co-work일반 협업/문서 작업용. Analyst·Technical Writer·Content Writer 등 6단계 비동기 워크플로우.

co-security레드팀/침투 테스트용. Red Team Lead·Pentester·Threat Modeler 등 6단계 파이프라인.

co-consult전략 컨설팅용. PM(Engagement Leader)이 지휘하는 7단계(Phase 0~6) 워크플로우. Strategy Analyst·Change Management Partner·Industry Expert·SME 등 10명의 전문 에이전트로 구성. 시장 분석 → 조직 진단 → 교차 검증(Phase 1.5) → 제안 승인 게이트(Phase 2) → 실무 솔루션 설계 → 납품 → PR/인도까지 컨설팅 프로젝트 전 과정을 다룬다.

co-deck beta강의·발표 자료 제작용. PM이 지휘하는 11단계(Stage 0~11) 파이프라인. Research → Source Verifier(신뢰도 검증) → Storyline → Design → Image Curation + Diagram Generation(병렬) → HTML Build → Layout Measure → PDF Export까지, 연구부터 인쇄용 PDF 출력까지 전 과정을 자동화한다. 5종 테마(outline, pitch, pitch-enhanced, vertical, zen)와 5종 스타일(premium-dark, classic, minimal, visual-heavy, academic)을 지원한다.

co-gameHTML5 Canvas 게임 개발용.

co-export beta수출입 무역 컨설팅용. PM과 8명의 전문 에이전트 — HS Classification Specialist, FTA Origin Analyst, Customs Duty Drawback Specialist, Export Control Compliance Specialist, Trade Documentation Specialist, Logistics Coordinator, Foreign Regulatory Intelligence Analyst, Market Entry Strategist.

co-hr betaHR/노동 관계 멀티 AI팀용. 대상 관할권의 노동법 컴플라이언스(국가 프로필 기반)와 HRM/HRD, 조직 설계, 변화 관리 컨설팅을 다룬다.

co-news beta상장기업을 다루는 경제/금융 저널리즘용. PM(편집장)과 6명의 전문 에이전트 — Financial Analyst, Legal Researcher, Fact-Checker, Reporter, Style Editor, Visual Editor. 국가 프로필 메커니즘(docs/countries/)으로 규제기관 재무 공시와 상법 리서치를 종합해 팩트체크된 기사를 작성한다 — KR 프로필 적용 시 한국 상장사 공시(DART) 등 국가 스코프 데이터를 사용한다.

co-price beta가격 관리 및 컨설팅 시뮬레이터용. K-Beauty 샘플 데이터셋을 포함해 가격 전략, 시뮬레이션, 컨설팅 산출물을 다룬다.

co-safety betaEHS/GxP 컴플라이언스 플랫폼용. 산업안전, 공정안전, 의약품 품질, 의료기기 안전 등 규제·위험 관리 워크플로우를 다룬다.

co-abapSAP ABAP 개발용.

각 베리언트(variant)는 git 태그 template-vX.Y.Z로 버전이 관리되며, bun scripts/validate-templates.ts가 에이전트 frontmatter의 완결성, 필수 섹션, AGENTS.md 로스터와의 정합성, .claude/·.gemini/·.agents/·.codex/ 플랫폼 표면 간 패리티 등 구조적 규정 준수를 검사한다.

templates/라는 이름이 가리키듯, 이 저장소가 배포하는 것은 결국 보일러플레이트(boilerplate)다. 매 프로젝트마다 처음부터 다시 작성해야 할 PM 역할 정의, 거버넌스 파이프라인, 플랫폼별 커맨드·스킬 배선을 미리 갖춰 둔 출발점이다. 다만 "복사해서 각자 알아서 고치는" 흔한 보일러플레이트와 달리, 이 저장소는 그 출발점이 어디서 왔고 어떻게 갱신되는지까지 계층 구조로 명시한다. 바로 다음 절의 L0 → L1 → L2 → L3다.

이 보일러플레이트가 미리 갖춰 두는 것 중 하나가 에이전트 역할별 모델 배정이다. variant 안의 각 에이전트 정의 파일(agents/*.md)은 frontmatter에 tier 필드를 갖고, 이 값은 플랫폼별(claude/gemini/antigravity/gemini-cli/codex)로 high/medium/low 중 하나를 지정한다. 판단이 무거운 역할(PM·Architect)에는 high, 실제 구현을 담당하는 역할(code-writer·docs-writer)에는 medium, 정형화된 반복 작업(automation-engineer 등)에는 low를 배정하는 식이다. 실제 model 필드는 보통 inherit로 남겨 두는데, 각 플랫폼이 배포 시점에 이 tier 값을 자기 쪽 모델 별칭(opus/sonnet/haiku)으로 번역해 배정하기 때문이다. 즉 보일러플레이트를 복제하는 순간, 새 프로젝트는 "누가 어떤 비용의 모델로 일하는가"까지 이미 정해진 채로 시작한다.

이 티어링이 없으면 실제로 무슨 문제가 생길까? 모든 에이전트를 획일적으로 최고 성능 모델(high)에 배정하면, automation-engineer처럼 정형화된 스크립트 실행만 반복하는 역할에도 매번 불필요하게 비싼 추론 비용이 들어가 팀 전체의 운영 비용이 무의미하게 커진다. 반대로 전부 최저 비용 모델(low)로 통일하면, PM처럼 여러 에이전트의 산출물을 종합해 판단해야 하는 역할이 얕은 추론만 하다가 잘못된 조율 결정을 내리는 일이 잦아진다. 티어링은 "이 역할이 실제로 얼마나 깊은 추론을 필요로 하는가"에 맞춰 비용과 품질의 균형을 역할 단위로 미리 맞춰 두는 장치다.

이 모델 비용 티어(high/medium/low)는 8장에서 다루는 L0 → L1 → L2 → L3 4-tier(파일이 어디서 왔고 어떻게 흐르는가에 대한 계층)와 이름의 "3단" 감각만 같을 뿐 서로 다른 개념이다. 하나는 "에이전트에게 어떤 모델을 배정할 것인가"이고, 다른 하나는 "파일의 원본이 어디에 있는가"다.

세션 시작 체크리스트와 스캐폴딩

CONSTITUTION.md는 모든 세션이 시작할 때 따라야 할 순서를 정의한다. 먼저 git config core.hooksPath .githooks로 git 훅 경로를 설정하고, CONSTITUTION.md 자체를 읽은 뒤, 작업 중인 프로젝트의 docs/context.md(프로젝트 설정 문서)를 읽는다. 이어서 AGENTS.md(에이전트 로스터)로 사용 가능한 에이전트를 확인하고, memory/YYYY-MM-DD.md에 이전 세션의 맥락이 남아 있는지 점검한 다음, docs/context.md가 지정한 스킬들을 로드한다.

새 프로젝트를 만드는 흐름은 개념적으로 단순하다. bun scripts/new-project.ts 스크립트에 프로젝트 이름과 원하는 베리언트(variant)를 지정해 실행하면, 그 베리언트(variant)의 전체 구성이 복제되어 완전히 독립된 git 저장소가 된다. 이 저장소는 워크스페이스 루트와 분리되어 있지만, 태어날 때부터 CONSTITUTION.md의 공유 표준을 상속한 상태로 시작한다. 팀은 그 안에서 프로젝트 고유의 docs/context.md와 프로젝트 레벨 CLAUDE.md/GEMINI.md/CODEX.md 오버라이드를 채워나가며 팀을 발전시킨다.

bun scripts/new-project.ts "my-project-name" --variant co-develop

이 명령의 전체 문법과 모든 옵션(--platform, --version)은 6장 §1 · 프로젝트 스캐폴딩 명령에서 직접 실습한다.

여기서 CONSTITUTION.md와 context.md의 관계를 분명히 해 둘 필요가 있다. 둘 다 "세션 시작 체크리스트"에서 읽는 문서지만 SSOT의 계층이 다르다. CONSTITUTION.md는 L0(워크스페이스 루트)에 단 하나만 존재하며 모든 프로젝트가 공유하는 규칙을 정의한다. 거버넌스, PR 워크플로우, 멀티 에이전트 원칙이 여기에 포함된다. 반면 context.md는 L3(개별 프로젝트)마다 따로 존재하며, 그 프로젝트만의 목표·도메인 지식·현재 진행 상태를 담는 프로젝트 전용 설정 문서다. CONSTITUTION.md가 위에서 강제해서 채워지는 파일이 아니라, 각 프로젝트 팀이 직접 써 나가는 파일이라는 점이 다르다. 그래서 체크리스트도 순서가 있다. CONSTITUTION.md로 "무엇을 지켜야 하는가(공통)"를 먼저 확인한 뒤, context.md로 "지금 이 프로젝트가 무엇을 하고 있는가(개별)"를 확인한다.

그런데 templates/<variant>/docs/context.md처럼 variant 안에도 같은 이름의 파일이 있다. 이것은 L3 프로젝트의 context.md와 이름만 같을 뿐 역할이 다르다. variant 안의 context.md는 아직 채워지지 않은 빈 골격(placeholder)이고, new-project.ts가 실행되는 순간 다른 L2→L3 파일들과 마찬가지로 딱 한 번 복제된다. 복제된 뒤에는 원본(베리언트(variant)의 context.md)과의 연결이 완전히 끊기고, 그 프로젝트 팀이 실제 내용으로 채워 나가는 독립된 문서가 된다. 그래서 이후 베리언트(variant)의 context.md 골격이 바뀌어도 이미 스캐폴딩된 프로젝트의 context.md에는 자동으로 반영되지 않는다.

workspace 루트의 파일(CONSTITUTION.md, CLAUDE.md 등)과 스캐폴딩된 개별 프로젝트의 파일은 서로 다른 git 저장소에 속한다. 둘을 같은 작업에서 함께 수정하지 않는 것이 저장소의 기본 원칙이다.

← 이전 장

4장 · 하네스 기반 멀티 에이전트 팀 활용

다음 장 →

6장 · 기존 variant 활용