ai-workspace-standards 살펴보기

ai-workspace-standards 저장소의 구조와 핵심 개념을 배웁니다. 4-레벨 레이어 구조(L0→L1→L2→L3), variant 개념, 핵심 파일(AGENTS.md, CLAUDE.md, GEMINI.md, CODEX.md)의 역할, 그리고 공통 컨트랙트를 이해합니다.

ai-workspace-standards란

정의

ai-workspace-standards는 Claude Code, Gemini CLI/Antigravity, Codex 같은 AI 코딩 도구를 활용하여 여러 AI 에이전트가 협력하는 프로젝트를 만들 때 필요한 오픈소스 표준 템플릿입니다. GitHub에서 무료로 공개되어 있으며, 누구나 복사해서 자신의 프로젝트에 적용할 수 있습니다.

• GitHub 저장소: github.com/5throck/ai-workspace-standards
• 라이선스: 오픈소스 (누구나 자유롭게 사용, 수정, 배포 가능)
• 지원 플랫폼: Claude Code, Gemini CLI/Antigravity, Codex CLI/Desktop App (세 플랫폼 모두 동일한 구조 사용, 각각 CLAUDE.md/GEMINI.md/CODEX.md로 지침 제공)

왜 표준이 필요한가?

프로젝트마다 AI 에이전트를 다르게 정의하고 관리하면 여러 가지 문제가 발생합니다. 표준 템플릿이 필요한 이유는 다음과 같습니다.

• 일관성 — 모든 프로젝트가 같은 구조를 따르면, 새 프로젝트에 합류한 팀원도 즉시 이해할 수 있습니다. 파일 위치, 에이전트 정의 방식, 규칙이 모두 동일하기 때문입니다.
• 재사용성 — 한 번 만든 에이전트나 스킬을 다른 프로젝트에서도 그대로 사용할 수 있습니다. 비슷한 작업을 매번 처음부터 정의할 필요가 없습니다.
• 협업 — 여러 사람이 함께 작업할 때, 공통된 "언어"와 "규칙"이 있으면 소통 오류를 줄이고 효율적으로 협력할 수 있습니다.
• 품질 보장 — 자동 검증 스크립트(audit, validate)가 표준 구조를 기반으로 동작하므로, 규칙 위반을 조기에 발견할 수 있습니다.

초보자 비유: 조직도와 업무 매뉴얼 템플릿

ai-workspace-standards를 이해하려면 회사에 비유해 보면 좋습니다. 회사를 설립하려면 조직도(누가 무슨 역할을 하는지)와 업무 매뉴얼(각자 어떻게 일해야 하는지)이 필요합니다. ai-workspace-standards는 바로 이 조직도와 업무 매뉴얼의 템플릿입니다. 이 템플릿을 복사해서 자기 회사(프로젝트)에 맞게 수정하면, 처음부터 완전한 조직 체계를 갖출 수 있습니다.

디렉토리 구조

ai-workspace-standards 저장소는 규칙적인 디렉토리 구조를 가지고 있습니다. 각 폴더가 명확한 역할을 담당하므로, 구조만 보면 프로젝트가 어떻게 구성되어 있는지 한눈에 파악할 수 있습니다.

최상위 디렉토리 개요

memory/ 폴더

최상위에는 memory/ 폴더도 있습니다. 이 폴더는 AI 세션의 기록, 회의록, 작업 로그 등을 저장하는 곳입니다. PM 에이전트가 각 세션의 진행 상황과 의사결정 기록을 memory/YYYY-MM-DD.md 파일로 남깁니다. 이렇게 하면 이전 세션에서 무엇을 했는지 다음 세션에서도 파악할 수 있습니다.

루트 파일들

최상위 디렉토리에는 폴더 외에도 중요한 파일들이 있습니다. AGENTS.md(에이전트 레지스트리), CLAUDE.md(Claude Code용 지침), GEMINI.md(Gemini CLI/Antigravity용 지침), CODEX.md(Codex CLI/Desktop App용 지침), CHANGELOG.md(변경 이력)가 모두 프로젝트 루트에 위치합니다. 이 파일들은 이 장의 "핵심 파일들" 섹션에서 자세히 다룹니다.

핵심 파일들

ai-workspace-standards의 핵심 파일들은 프로젝트 루트에 위치하며, 각각 명확한 역할을 수행합니다. 이 섹션에서는 가장 중요한 6개 파일을 설명합니다.

AGENTS.md — 에이전트 레지스트리

AGENTS.md는 프로젝트에 속한 모든 AI 에이전트의 정의, 역할, Tier, 파견 트리거를 등록하는 "공식 명부"입니다. 이 파일을 열면 표 형태로 모든 에이전트가 나열되어 있고, 각 에이전트의 세부 정의 파일(agents/pm.md, agents/research.md 등)로 연결되는 링크가 있습니다.

AGENTS.md에는 다음 정보가 포함됩니다.

• 에이전트 로스터 — 모든 에이전트의 이름, 파일 위치, Tier(우선순위), 역할
• PM Gateway 워크플로우 — PM이 어떻게 에이전트를 파견하는지에 대한 규칙
• 파견 트리거 — 어떤 상황에서 어떤 에이전트를 호출해야 하는지
• 실행 계획 템플릿 — 작업을 계획할 때 사용하는 표준 형식

초보자 비유: AGENTS.md는 회사의 "직원 명부"입니다. 직원 명부에는 각 직원의 이름, 직급(Tier), 담당 업무가 적혀 있습니다. 마찬가지로 AGENTS.md에는 각 AI 에이전트의 이름, 등급, 역할이 명확하게 정의되어 있습니다.

CLAUDE.md — Claude Code용 행동 지침

CLAUDE.md는 Claude Code(Anthropic의 AI 코딩 도구)가 프로젝트에서 동작할 때 따라야 할 행동 지침입니다. 이 파일에는 Claude가 어떤 에이전트 역할을 수행할 수 있는지, 어떤 도구를 사용할 수 있는지, 어떤 규칙을 지켜야 하는지가 상세하게 기술됩니다.

CLAUDE.md의 핵심 내용은 다음과 같습니다.

• 에이전트 디스패치 규칙 — PM이 어떤 상황에 어떤 에이전트를 보내는지
• 3-Tier 전략 — High/Medium/Low 모델을 언제 사용하는지
• 게이트 프로토콜 — 사용자 승인이 필요한 단계와 자동 진행 단계
• 도구 사용 권한 — 각 에이전트가 사용할 수 있는 도구의 범위

초보자 비유: CLAUDE.md는 Claude에게 주는 "업무 지시서"입니다. 직원에게 "이런 작업이 들어오면 이 담당자에게 넘겨라", "이 단계에서는 반드시 관리자 승인을 받아라"라고 적어놓은 메뉴얼과 같습니다.

GEMINI.md — Gemini CLI/Antigravity용 행동 지침

GEMINI.md는 Gemini CLI와 Antigravity(Google의 AI 코딩 도구)용 행동 지침입니다. 내용과 구조는 CLAUDE.md와 동일한 역할을 하며, 단지 Claude Code 대신 Gemini CLI/Antigravity를 사용할 때 적용된다는 점이 다릅니다.

두 파일이 왜 따로 존재할까요? Claude Code와 Antigravity는 각각 다른 회사에서 만든 도구이므로, 모델 이름, 도구 호출 방식, 시스템 프롬프트 형식이 다릅니다. 하지만 에이전트 구조, 워크플로우, 게이트 규칙은 완전히 동일합니다. 따라서 CLAUDE.md와 GEMINI.md는 "같은 규칙, 다른 도구 설정"이라고 이해하면 됩니다.

CODEX.md — Codex CLI/Desktop App용 행동 지침

CODEX.md는 세 번째 플랫폼인 Codex(CLI와 Desktop App 모두 포함)용 행동 지침입니다. CLAUDE.md, GEMINI.md와 동일하게 PM Gateway 워크플로우, 에이전트 디스패치 규칙을 담고 있지만, 한 가지 중요한 차이가 있습니다 — Codex에는 네이티브 서브에이전트 도구가 없어서, PM이 각 전문 에이전트의 정의 파일(agents/<name>.md)을 역할 컨텍스트로 불러온 뒤 세션 안에서 순차적으로 단계를 직접 수행합니다. 또한 Codex는 워크스페이스의 훅(Hook) 스위트를 실행하지 않으므로, 거버넌스 규칙은 프롬프트로 자체 강제됩니다(Antigravity와 동일한 방식).

CHANGELOG.md — 변경 이력 기록

CHANGELOG.md는 프로젝트의 모든 변경 사항을 시간순으로 기록하는 파일입니다. 새 에이전트가 추가되거나, 스킬이 수정되거나, 규칙이 변경될 때마다 여기에 기록됩니다. 버전 관리 시스템(Git)의 커밋 로그와 달리, CHANGELOG는 사용자가 읽을 수 있는 형태로 변경 내용을 요약합니다.

context.md (docs/ 폴더 내) — L2/L3 프로젝트 심화 설정

docs/context.md는 L2 variant 템플릿 및 L3 프로젝트에만 존재하는 심화 설정 파일입니다. 워크스페이스 루트(L0)에는 없으며, L0의 SSOT는 AGENTS.md입니다. 주요 내용은 다음과 같습니다.

• L0 → L1 → L2 → L3 레이어 구조의 구체적 정의
• 에이전트 파일의 frontmatter 스펙
• 라이프사이클 관리 절차
• 거버넌스 문서의 구조

이 파일은 "시스템 설정"에 가까우므로, 초보자 단계에서는 내용을 완전히 이해하지 않아도 괜찮습니다. 프로젝트를 운영하면서 점차 깊이 있게 참조하게 됩니다.

핵심 파일 비교

4-레벨 레이어 구조

ai-workspace-standards의 가장 중요한 설계 원리 중 하나가 4-레벨 레이어 구조입니다. 워크스페이스의 자원이 원본 소스(L0)에서 출발하여 공통 인프라(L1), variant 템플릿(L2), 실제 프로젝트(L3)로 전달되는 계층 구조입니다.

L0 Source (Workspace Root) — 원본 소스

L0 Source는 워크스페이스 루트 디렉토리 자체입니다. 모든 에이전트, 스킬, 스크립트가 작성되는 유일한 편집 위치이며, 변경이 다른 모든 레이어로 전달되는 출발점입니다.

• 공통 에이전트 — PM 에이전트 등 모든 프로젝트가 사용하는 기본 에이전트
• 공통 스킬 — 어디서든 재사용 가능한 기본 스킬
• 코어 스크립트 — audit.ts, validate-templates.ts 등 핵심 자동화 도구
• AGENTS.md — 글로벌 에이전트 레지스트리

L1 (Common Template) — 공통 인프라 레이어

L1은 templates/common/에 위치한 공통 인프라 레이어입니다. L0 Source에서 배포된 내용을 기반으로, 모든 variant가 공유하는 템플릿을 제공합니다. 플랫폼별 설정과 표준 디렉토리 구조가 포함됩니다.

• .claude/ 디렉토리 — Claude Code용 설정, 명령어, 스킬
• .gemini/ 디렉토리 — Gemini CLI/Antigravity용 설정, 명령어, 스킬
• .codex/ 디렉토리 — Codex CLI/Desktop App용 설정, 프롬프트, 스킬
• 플랫폼별 에이전트 설정 (CLAUDE.md, GEMINI.md, CODEX.md)
• 공통 에이전트 템플릿, 공통 스킬, 스크립트
• propagation-map.json — L0→L1 배포 규칙 정의

참고: L1은 직접 편집하지 않습니다. L0 Source에서 bun run propagate:apply를 통해 변경 사항이 자동으로 배포됩니다.

L2 (Variant Template) — variant 템플릿 레이어

L2는 templates/co-*/에 위치한 variant 템플릿 레이어입니다. 각 variant(co-deck, co-consult 등)는 L1을 기반으로 자신만의 에이전트, 스킬, 설정을 추가한 템플릿입니다.

• variant 전용 에이전트 (예: co-deck의 image-curator, pdf-export)
• variant 전용 스킬 (예: co-deck의 html-build, storyline)
• variant 설정 (variant.json, PM 에이전트 YAML 오버라이드)
• L1의 공통 템플릿 상속 (variant.json의 inherits_common: "templates/common")

현재 13개의 variant 템플릿이 존재합니다: co-abap, co-consult, co-deck, co-design, co-develop, co-export, co-game, co-hr, co-news, co-price, co-safety, co-security, co-work.

L3 (Project) — 실제 프로젝트 레이어

L3는 Projects/*/에 위치한 실제 프로젝트 레이어입니다. L2 variant 템플릿을 기반으로 스캐폴딩(scaffolding)된 개별 프로젝트입니다. 각 프로젝트는 독립적으로 운영되며, 로컬 커스터마이징이 가능합니다.

• docs/context.md — 프로젝트의 심화 설정 (프로젝트 생성 후 불변)
• 프로젝트 전용 에이전트, 스킬, 스크립트
• variant.json — L2에서 복사된 메타데이터
• 실제 작업 산출물이 생성되는 공간

배포 경로와 레이어 구조

이 시스템에서는 두 가지 방향을 구분하는 것이 중요합니다.

• 배포 경로 (L0 → L1 → L2): 원본 소스(L0)의 변경 사항이 propagate:apply를 통해 L1 공통 템플릿으로, 그리고 각 L2 variant 템플릿으로 전달되는 방향입니다. 이것은 코드가 흐르는 방향입니다.
• 레이어 구조 (L1 → L2 → L3): 각 레이어가 상위 레이어의 템플릿을 기반으로 구축되는 정적 계층 관계입니다. L3 프로젝트는 L2 variant 템플릿에서 스캐폴딩되며, L2는 L1의 공통 템플릿을 상속받습니다.

L2 → L3: 실제로 프로젝트 만들기

위 다이어그램의 "스캐폴딩" 화살표는 실제로는 워크스페이스 루트에서 스크립트 하나를 실행하는 것입니다. new-project.ts 스크립트가 선택한 L2 variant 템플릿(templates/co-*/)을 읽어, Projects/<project-name>/에 실제로 동작하는 L3 프로젝트를 생성합니다.

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

이 명령을 실행하면 스크립트가 다음을 자동으로 수행합니다.

• templates/co-consult/(L2)의 에이전트, 스킬, 설정을 Projects/my-project/로 복사
• templates/common/(L1)의 공통 인프라도 함께 적용
• variant.json을 프로젝트 루트에 배치하고 프로젝트 이름으로 갱신
• docs/context.md 등 프로젝트별 설정 파일 생성

--variant에는 co-consult, co-deck을 포함해 현재 존재하는 13개 variant 중 하나를 지정할 수 있습니다. 6장·7장의 실습에서 사용하는 co-consult, co-deck 예제는 별도의 저장소를 클론하는 것이 아니라, 공개 저장소 ai-workspace-standards 안의 templates/co-consult/, templates/co-deck/(L2)를 위 명령으로 직접 스캐폴딩한 결과물입니다.

덮어쓰기 규칙

하위 레이어는 상위 레이어의 설정을 덮어쓸 수 있지만, 반대 방향으로는 영향을 주지 않습니다. 이것은 객체지향 프로그래밍의 클래스 상속과 같은 원리입니다.

• L3에서 설정한 규칙이 L2, L1, L0의 규칙보다 우선합니다.
• L2에서 설정한 규칙이 L1, L0의 규칙보다 우선합니다 (단, L3에서 덮어쓰지 않은 경우).
• L1에서 설정한 규칙이 L0의 규칙보다 우선합니다 (단, L2, L3에서 덮어쓰지 않은 경우).
• L0의 규칙은 어디에서도 덮어쓰지 않으면 모든 레이어에 적용됩니다.

variant(변형) 개념

variant란 무엇인가?

variant(변형)는 ai-workspace-standards의 L0 + L1 템플릿을 기반으로, 특정 용도에 맞게 커스터마이징한 템플릿입니다. 앞서 4-레벨 레이어 구조에서 설명한 L2가 바로 variant 템플릿에 해당하며, L3은 이 L2 템플릿을 스캐폴딩하여 만든 실제 프로젝트입니다.

모든 variant는 동일한 "뼈대"(L0 + L1)를 공유하지만, 각자의 목적에 따라 다른 에이전트, 스킬, 설정을 추가합니다. 마치 같은 자동차 플랫폼에서 세단, SUV, 스포츠카 등 다양한 변형 모델이 만들어지는 것과 같습니다.

variant의 예시

현재 ai-workspace-standards 생태계에는 다음과 같은 variant들이 있습니다.

• co-consult — AI 컨설팅 실습용 variant. 기업 분석, 전략 수립, 보고서 작성을 자동화하는 에이전트 팀을 제공합니다. 이 핸드북 6장에서 실습합니다.
• co-deck — 프레젠테이션 자동화용 variant. 연구 → 스토리라인 → 디자인 → HTML 빌드 → PDF 출력까지 전체 파이프라인을 자동화합니다. 11단계 워크플로우를 제공합니다.
• co-price — 🔶 Beta. 다업종 가격 관리·컨설팅 시뮬레이터. K-Beauty 샘플 데이터셋이 함께 제공됩니다.
• co-safety — 🔶 Beta. EHS/GxP 준수 플랫폼 워크플로우. 40개 이상의 전문 에이전트(비상대응, 컴플라이언스, 법무, 교육, PSM, 리스크, 감사 등)를 포함합니다.
• 그 외 co-abap, co-design, co-develop, co-export, co-game, co-hr, co-news, co-security, co-work 등 다양한 목적의 variant가 있습니다.

variant.json — variant의 메타데이터

각 variant는 variant.json 파일을 통해 자신의 메타데이터를 정의합니다. 이 파일에는 다음 정보가 포함됩니다.

• 이름 — variant의 식별자 (예: "co-deck", "co-consult")
• 버전 — variant의 현재 버전 (예: "1.0.0")
• 상태 — draft, beta, stable 등 현재 개발 단계
• 의존성 — 상위 레벨(L0, L1)에 대한 의존 관계
• 설명 — variant의 용도와 특징

{
  "name": "co-deck",
  "description": "프레젠테이션·강의 자료 제작 variant",
  "variant_type": "lecture",
  "status": "beta",
  "version": "0.2.0",
  "inherits_common": "templates/common",
  "agents": [
    { "name": "pm",              "file": "agents/pm.md" },
    { "name": "research",         "file": "agents/research.md" },
    { "name": "storyline",       "file": "agents/storyline.md" },
    { "name": "html-build",      "file": "agents/html-build.md" }
  ]
}

variant.json은 variant를 설치하고 관리할 때 참조되는 "신분증"과 같은 역할을 합니다. 이 파일이 있어야 시스템이 어떤 variant인지, 어떤 버전인지, 어떤 의존성이 있는지 파악할 수 있습니다.

variant의 생애주기

variant는 다음과 같은 생애주기를 거칩니다.

• draft — 초기 개발 단계. 기본 구조만 갖춘 상태
• beta — 테스트 단계. 주요 기능이 구현되었으나 안정성 검증이 필요
• stable — 안정 단계. 실제 사용에 적합
• deprecated — 사용 중단. 더 이상 유지보수되지 않음

이 생애주기는 docs/VERSION_MANIFEST.md에서 중앙 관리됩니다. 새 variant를 만들면 draft로 시작하여, 충분한 테스트를 거친 후 stable로 승격됩니다.

variant로부터 새 프로젝트 만들기

6장·7장 실습에서는 시간을 아끼기 위해 미리 만들어진 예시 프로젝트(co-consult, co-deck)를 clone해서 사용합니다. 하지만 실제 일상 업무에서는 clone을 하지 않습니다 — 워크스페이스 루트에서 명령어 한 줄로 L2 variant 템플릿으로부터 완전히 새로운 L3 프로젝트를 스캐폴딩(scaffolding)합니다.

bun scripts/new-project.ts "my-market-report" --variant co-consult

이 명령은 Projects/my-market-report/를 독립된 새 Git 저장소로 생성하고, co-consult의 에이전트·스킬·설정을 복사한 뒤, 이 프로젝트만의 목표를 채워 넣을 수 있도록 비어 있는 docs/context.md 골격을 렌더링합니다. 전체 문법은 다음과 같습니다.

bun scripts/new-project.ts "<프로젝트-이름>" --variant <variant> [--platform claude|antigravity|codex|all] [--version X.Y.Z] [--country <CODE>]

• <프로젝트-이름> — 필수. Projects/ 아래 폴더 이름이 됩니다.
• --variant <variant> — 필수. 어떤 L2 템플릿에서 스캐폴딩할지 지정합니다(co-consult, co-deck, co-develop 등).
• --platform — 선택. 어떤 플랫폼 설정(.claude/, .gemini/, .codex/)을 복사할지 제한합니다(claude, antigravity, codex, all). 기본값은 all로 세 플랫폼(Claude Code + Gemini/Antigravity + Codex) 전부를 복사하며, 하나를 지정하면 그 플랫폼만 남습니다. 구버전의 both는 2026-09-20부로 all로 바뀌었고, 이제는 Codex까지 함께 포함합니다.
• --version — 선택. 원본 variant의 현재 버전 대신 특정 템플릿 버전을 고정해서 사용합니다.
• --country <CODE> — 선택. 한국 대상 프로젝트라면 --country KR을 지정하세요. 국가 프로파일이 한국 전용 스킬 여섯 개(k-dart·k-law·k-kosis·k-opendata, 그리고 2026-09부터 k-ecos·k-krx)와 KR API 키 설정을 프로젝트에 함께 넣어 줍니다 (자세한 내용은 별첨 D 참조).

공통 컨트랙트

컨트랙트란 무엇인가?

컨트랙트(Contract)는 에이전트, 스킬, 스크립트가 모두 지켜야 하는 공통 규칙입니다. 프로그래밍에서 "인터페이스(Interface)"나 "규약(Protocol)"과 같은 개념으로, 모든 참여자가 동일한 형식과 규칙을 따르도록 강제합니다.

초보자 비유: 컨트랙트는 "공통 언어"입니다. 다국어 사용자가 회의할 때 모두 같은 언어(예: 영어)를 사용하기로 약속하면, 원활하게 소통할 수 있습니다. 마찬가지로, 모든 에이전트가 같은 컨트랙트를 따르면 서로 충돌 없이 협력할 수 있습니다.

거버넌스 컨트랙트 — 어디에 정의되어 있는가?

거버넌스 컨트랙트(공통 규칙)는 단일 JSON 파일이 아니라, 워크스페이스의 핵심 거버넌스 문서들에 분산 정의되어 있습니다.

• CONSTITUTION.md — 워크스페이스 전체의 마스터 공유 표준. 거버넌스 규칙, PR 워크플로우, 멀티 에이전트 아키텍처 원칙 등
• AGENTS.md — L0(워크스페이스 루트)의 SSOT. 에이전트 레지스트리, PM Gateway 워크플로우, 스킬 로스터 등
• docs/context.md (L2/L3 프로젝트 전용) — 각 variant 및 프로젝트의 심화 설정. 프로젝트 타입, 상태, 아키텍처, 핵심 파일 등

이 문서들은 에이전트, 스킬, 스크립트가 모두 지켜야 하는 공통 규칙을 정의합니다. 프로그래밍에서 "인터페이스(Interface)"나 "규약(Protocol)"과 같은 개념으로, 모든 참여자가 동일한 형식과 규칙을 따르도록 강제합니다.

컨트랙트의 3가지 역할

거버넌스 컨트랙트는 다음 세 가지 핵심 역할을 수행합니다.

• 일관성 보장 — 모든 프로젝트가 같은 형식을 사용하므로, 한 프로젝트의 파일을 다른 프로젝트에서도 즉시 이해할 수 있습니다. 에이전트 파일이 어디에 있는지, 어떤 필드가 필수인지 알 수 있습니다.
• 호환성 유지 — 새 variant를 만들 때 컨트랙트를 따르기만 하면, 기존 도구(audit, validate)와 자동으로 호환됩니다. 별도의 설정이나 변환 과정이 필요 없습니다.
• 자동 검증 가능 — bun scripts/audit.ts 등의 스크립트가 파일을 자동으로 검사하고 규칙 위반을 감지할 수 있습니다. 사람이 일일이 확인하지 않아도 됩니다.

컨트랙트 적용 단계

새 에이전트나 스킬을 만들 때 컨트랙트를 적용하는 과정은 다음과 같습니다.