6장 §1

ai-workspace-standards 로컬 설치와 프로젝트 스캐폴딩

워크스페이스를 로컬에 세팅하고, 기존 베리언트(variant)로 프로젝트를 스캐폴딩하는 방법을 다루는 레퍼런스  |  공식 문서: ai-workspace-standards

대상 저장소ai-workspace-standards
대상 브랜치main
참조 문서 URLgithub.com/5throck/ai-workspace-standards
문서 수집일2026-07-14
버전 확인 방법git --version, bun --version으로 로컬 도구 버전 확인. 워크스페이스 자체는 templates/VERSION과 각 베리언트(variant)의 template-vX.Y.Z 태그로 버전을 관리한다.
개정 시 확인 사항저장소의 CONSTITUTION.md, scripts/new-project.ts, scripts/list-template-versions.ts가 바뀌었는지 원본 저장소에서 재확인한다.

전체 구조 개요

ai-workspace-standards/                (워크스페이스 루트로 클론)
├── CONSTITUTION.md                    공유 표준 — 가장 먼저 읽는 파일
├── CLAUDE.md / GEMINI.md / AGENTS.md  플랫폼별 동작·에이전트 로스터
├── templates/                         variant(프로젝트 템플릿) 모음
│   ├── co-develop/                    소프트웨어 개발 6단계 파이프라인
│   ├── co-design/                     UI/UX 5단계 워크플로우
│   ├── co-work/                       일반 협업/문서 6단계 워크플로우
│   └── ...                            co-security, co-consult, co-deck 등
├── scripts/                           new-project.ts 등 운영 스크립트(TypeScript, bun으로 실행)
└── Projects/                          <프로젝트명>/ 형태의 개별 프로젝트(각자 독립 git 저장소)

Variant 13종 전체 목록

Variant목적
co-abapSAP ABAP 개발 — ABAP 기반 엔터프라이즈 애플리케이션 개발
co-work일반 협업/문서 — 공통 비동기 워크플로우
co-consult전략 컨설팅 — 고객 문제 진단 및 제안서 작성
co-deck beta프레젠테이션 — 리서치부터 인쇄용 PDF까지 11단계 파이프라인
co-develop소프트웨어 개발 — 6단계 개발 파이프라인
co-designUI/UX 디자인 — 반복적 디자인 워크플로우
co-security보안 검토 — 레드팀/침투 테스트 워크플로우
co-game게임 개발 — Vanilla TypeScript 기반 HTML5 Canvas 게임
co-export beta수출입 무역 컨설팅
co-hr betaHR/노동 관계 — 노동법 컴플라이언스·HRM/HRD·조직 설계 컨설팅
co-news beta상장기업을 다루는 경제/금융 저널리즘 — 국가 프로필(KR) 기반 공시·상법 리서치
co-price beta가격 관리 및 컨설팅 시뮬레이터 — K-Beauty 샘플 데이터셋 포함
co-safety betaEHS/GxP 컴플라이언스 플랫폼 — 산업안전·공정안전·품질 규제 워크플로우

저장소 구조 둘러보기 — clone 후 처음 확인할 곳 5곳

git clone으로 워크스페이스 루트에 저장소를 복제한 뒤, 가장 먼저 확인할 핵심 디렉터리 5곳을 순서대로 짚어본다. 이 순서는 5장에서 다룬 "런타임 흐름"과 일치한다.

  1. CONSTITUTION.md — 가장 먼저 읽을 파일. 워크스페이스 전체의 공유 표준(거버넌스, PR 워크플로우, 멀티 에이전트 원칙)이 정의되어 있다.
  2. CLAUDE.md / GEMINI.md / CODEX.md — 사용하는 AI 코딩 도구에 맞는 파일을 확인. 각 플랫폼별 동작 방식(훅, 슬래시 커맨드, 프롬프트, 에이전트 디스패치 규칙)이 정의되어 있다.
  3. AGENTS.md — 이 워크스페이스에서 호출 가능한 에이전트 로스터. "누가 어떤 역할을 하는가"를 한눈에 확인할 수 있다.
  4. templates/ — 사용 가능한 variant 13종이 이 디렉터리 아래에 있다. 각 variant 폴더를 열어 에이전트 구성과 거버넌스 파이프라인을 살펴본다.
  5. scripts/ — new-project.ts가 여기에 있다. 이 스크립트가 베리언트(variant)를 실제 프로젝트로 복제하는 핵심 명령이다.
이 둘러보기는 4장 실습에서 에이전트를 직접 만지기 전에, "이 저장소가 무엇을 담고 있는지"를 감을 잡기 위한 짧은 안내다. 실습 시간에는 이 5곳만 먼저 열어보고, 나머지 구조는 필요할 때마다 돌아와서 확인하는 방식으로 진행한다.

1. 로컬 환경 준비

git clone. 워크스페이스 루트로 클론

ai-workspace-standards는 일반적인 라이브러리처럼 프로젝트 안에 넣는 게 아니라, 워크스페이스 자체의 루트로 클론해서 쓰도록 설계되어 있다. 예를 들어 Windows에서는 C:\git, macOS/Linux에서는 ~/git 같은 위치에 이 저장소를 클론하면, 그 아래에서 만드는 모든 프로젝트가 CONSTITUTION.md의 공유 규칙을 자동으로 물려받는다.

만약 이 규칙을 무시하고 특정 프로젝트 폴더 안에(예: my-project/ai-workspace-standards/처럼) 서브모듈처럼 넣어버리면 어떻게 될까? new-project.ts 같은 스크립트는 "워크스페이스 루트에서 실행됐는가"를 스스로 확인하는데, 이 조건이 깨지므로 스캐폴딩 자체가 거부되거나, 경로 계산이 어긋나 엉뚱한 위치에 프로젝트가 생성된다. 게다가 그 프로젝트 하나만 공유 규칙을 물려받고 나중에 만들 다른 프로젝트들은 규칙을 전혀 공유하지 못해, 애초에 "워크스페이스 전체가 같은 표준을 쓴다"는 이 저장소의 존재 이유 자체가 무너진다.

git clone https://github.com/5throck/ai-workspace-standards.git C:\git
cd C:\git

bun. 런타임 설치

워크스페이스의 모든 운영 스크립트(scripts/*.ts)는 TypeScript로 작성되어 있고 bun으로 실행한다. 별도의 .sh/.ps1 버전은 존재하지 않으므로, bun 설치가 선행되어야 스크립트를 돌릴 수 있다.

bun --version
git --version

💡 핵심 한 줄: 두 명령이 모두 정상적으로 버전을 출력하면 로컬 환경 준비는 끝난 것이다.

세션 시작 체크리스트

CONSTITUTION.md가 정의하는 세션 시작 체크리스트는 다음 순서를 따른다.

  1. git hooks 경로 설정: git config core.hooksPath .githooks
  2. CONSTITUTION.md 읽기: 워크스페이스 공유 표준 확인
  3. 프로젝트 docs/context.md 읽기: 프로젝트 설정 확인
  4. AGENTS.md 읽기: 해당 프로젝트의 에이전트 로스터 확인
  5. memory/YYYY-MM-DD.md 확인: 이전 세션에서 남긴 컨텍스트 확인
  6. docs/context.md가 지정한 skill 로드

2. 프로젝트 스캐폴딩 명령

bun scripts/list-template-versions.ts. 사용 가능한 variant 확인

새 프로젝트를 만들기 전에, 워크스페이스에 어떤 variant들이 있고 각각 어떤 버전이 태그되어 있는지 먼저 확인한다.

bun scripts/list-template-versions.ts

bun scripts/new-project.ts. 기존 베리언트(variant)로 프로젝트 생성

가장 자주 쓰는 명령이다. variant 하나를 골라 프로젝트 이름과 함께 실행하면, templates/<variant>/의 전체 구성(에이전트 정의, 스킬, 커맨드, 거버넌스 파이프라인)이 새 독립 저장소로 복제된다.

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

특정 버전을 고정해서 스캐폴딩하고 싶다면 --version을 함께 지정한다.

bun scripts/new-project.ts "my-project-name" --variant co-develop --version 1.4.0
옵션설명비고
--variant 사용할 프로젝트 템플릿(co-develop, co-design, co-work 등)을 지정 생략 시 대화형으로 선택하거나 기본값을 사용(스크립트 동작에 따라 다름)
--version 해당 베리언트(variant)의 특정 template-vX.Y.Z 태그를 고정해서 사용 생략하면 최신 버전 사용

스캐폴딩 독립 git 저장소 공유 표준 상속

스캐폴딩된 프로젝트는 워크스페이스 루트와는 별개의 독립 git 저장소로 생성된다. 워크스페이스 루트 파일과 새 프로젝트 파일을 같은 작업/커밋에서 섞어 수정하지 않도록 주의한다.

신규 베리언트(variant)를 직접 만들고 싶다면

기존 variant로는 부족하고 완전히 새로운 도메인 팀 구성이 필요하다면, create-variant 스킬과 bun scripts/create-l3-scaffold.ts <variant-name> --domain <type> 명령으로 Projects/<variant-name>/ 아래에 독립된 Phase A 프로토타입을 먼저 만들 수 있다. 이 프로토타입은 정식 templates/ 베리언트(variant)로 승격(promote)되기 전까지 자유롭게 발전시킬 수 있다. 이 흐름의 자세한 단계와 승격 절차는 11장(신규 생성 D-1)과 12장(승격 P-1)에서 다룬다.

3. 참고 링크

ai-workspace-standards main 브랜치 기준 | 2026년 7월