새 variant 만들기와 기존 프로젝트의 variant 승격

6장 §2에서는 co-retail이라는 신규 베리언트(variant)를 처음부터 스캐폴딩하는 과정을 실습했다. 그런데 ai-workspace-standards에는 이것과는 결이 다른 두 번째 경로가 하나 더 있다. 이미 잘 돌아가고 있는, 템플릿으로 만들 생각 없이 시작했던 프로젝트를 나중에 정식 베리언트(variant)로 "승격"시키는 경로다. 이 장에서는 두 경로가 개념적으로 어떻게 다른지, 그리고 어떤 상황에 어느 쪽을 택해야 하는지를 다룬다.

출처: ai-workspace-standards (GitHub)

두 경로의 차이

새로운 베리언트(variant)를 워크스페이스에 추가하는 방법은 하나가 아니다. ai-workspace-standards는 두 가지 서로 다른 출발점을 인정한다. 하나는 "아직 아무 프로젝트도 없는 상태에서, 처음부터 템플릿이 될 것을 염두에 두고 설계하는" 경로다. 다른 하나는 "원래 템플릿으로 만들 생각이 전혀 없이 시작했던 프로젝트가, 시간이 지나며 여러 팀이 손으로 복사해 쓸 만큼 검증된 뒤에야 뒤늦게 템플릿으로 승격되는" 경로다.

이 둘의 차이는 단순히 "명령어가 다르다"는 수준이 아니다. 전자는 설계가 먼저고 사용은 나중이며, 후자는 사용(그리고 검증)이 먼저고 템플릿화는 나중이다. 워크스페이스가 이 두 경로를 모두 지원하는 이유는, 새로운 도메인의 에이전트팀을 만드는 실제 상황이 이 두 형태 중 하나로 수렴하기 때문이다.

처음부터 만드는 경로

그린필드 상태에서 시작하는 이 경로는 두 단계로 나뉜다. 먼저 create-variant 스킬과 bun scripts/create-l3-scaffold.ts <variant-name> --domain <type> [--country <CODE>]로 Projects/<variant-name>/ 아래에 독립된 "Phase A 프로토타입"을 만든다. 이 단계는 워크스페이스 문서에서 "L1-L2 Fork Model"이라고 부르는 구조의 일부로, 아직 정식 templates/ 소속이 아니기 때문에 자유롭게 실험하고 방향을 바꿀 수 있다. 11장 실습(D-1)에서 만드는 co-retail 프로토타입이 바로 이 Phase A 단계에 해당한다. 이 실습은 6장 §2 실습(D-1)을 참고한다.

프로토타입이 충분히 성숙하면 promote-variant 스킬을 통해 "Phase B 승격"을 거쳐 정식 templates/co-<name>/가 된다. 즉 처음부터 만드는 경로도 결국 승격 단계를 통과한다. 다만 그 프로토타입 자체가 애초에 템플릿이 될 것을 전제로 설계되었다는 점이 다음 절의 경로와 구분되는 지점이다。

스캐폴딩 명령은 선택 플래그 --country도 지원한다(예: --country KR). 국가 프로필(country-profile) 메커니즘은 DART 조회나 법령 검색처럼 특정 국가의 데이터 체계에 접근하는 스킬을 국가 코드로 스코핑하여, k-dart·k-law·k-kosis 같은 KR 공통 스킬을 --country KR 프로젝트에만 주입한다. KOSIS_API_KEY 같은 자격 증명 역시 국가 스코프 자산으로 분류되어 해당 프로젝트에만 배포된다. 설계 근거는 워크스페이스 문서 ADR-0057과 ADR-0058에, 실제 프로필 정의는 각 프로젝트의 docs/countries/KR.md에 문서화되어 있다.

기존 프로젝트를 승격하는 경로

두 번째 경로는 출발점 자체가 다르다. 어떤 팀이 특정 도메인 문제를 풀기 위해 프로젝트를 하나 만들었는데, 그 프로젝트가 다른 템플릿을 원형으로 삼지도 않았고 애초에 재사용을 염두에 두지도 않았다. 그런데 시간이 지나면서 그 프로젝트의 구성이 워낙 잘 작동해서, 사내 다른 팀들이 파일을 손으로 복사해가며 비슷한 걸 만들기 시작한다. 이런 "이미 검증된, 하지만 템플릿으로는 태어나지 않은" 프로젝트를 정식 베리언트(variant)로 전환하는 것이 승격의 목적이다.

이 경로도 결국 같은 promote-variant 스킬과 bun scripts/l3-to-variant-pipeline.ts --l3-path=Projects/<name> --name=co-<name> --type=<type> --description="<설명>" 파이프라인을 사용한다는 점에서 처음부터 만드는 경로의 Phase B와 메커니즘은 같다. --description과 선택 플래그인 --version(기본값 0.1.0), --status(기본값 beta)는 승격 결과물인 templates/<name>/variant.json에 직접 기록된다. 승격 전에는 PROMOTION_CHECKLIST.md의 조건들(bun run agent:verify, bun scripts/validate-skills.ts, bun scripts/audit.ts 통과 여부 등)을 모두 충족해야 한다는 게이트가 있다. 파이프라인 실행 후에는 variant.json의 inherits_common 버전 확인, 공통 파일과 중복되는 부분을 제거하는 "reconcile" 단계, 그리고 .claude/·.gemini/·.agents/·.codex/ 네 플랫폼(Claude/Gemini/Antigravity/Codex) 사이의 플랫폼 패리티 검증이 뒤따른다. 이 파이프라인이 자동으로 처리하지 못하는 도메인 고유 디렉터리(예: workflows/, regulations/ 같은)는 _ORIGIN.md가 지정한 대로 수동으로 옮겨야 한다.

"reconcile"과 "_ORIGIN.md 수동 이관"이 실제로 무엇을 하는지 구체적인 예로 풀어보자. 재무팀이 만든 Projects/budget-review/를 승격한다고 하면, 이 프로젝트에는 두 종류의 파일이 섞여 있다. ① PM 정의나 세션 체크리스트처럼 templates/common/에 이미 있는 공통 파일을 그대로 복사해 온 것, ② regulations/ 폴더 안 사내 회계 규정 문서처럼 이 프로젝트만의 고유 자산. reconcile 단계는 ①에 해당하는 파일들을 "복사본"에서 "공통 파일을 상속하는 참조"로 되돌려, 나중에 templates/common/이 갱신될 때 이 variant도 함께 최신화되게 만든다. 반면 ②는 파이프라인이 그 존재 자체를 알 방법이 없으므로, 원 프로젝트에 남겨 둔 _ORIGIN.md의 "Manual Phase B Steps" 목록에 "regulations/ 폴더를 신규 베리언트(variant)로 수동 복사할 것"처럼 명시해 두고, 승격 담당자가 체크리스트를 보며 하나씩 직접 옮긴다.

어느 경로를 언제 선택할 것인가

결국 선택 기준은 하나로 요약된다. 참고할 선례가 전혀 없는 새로운 도메인이라면 처음부터 설계하는 경로가 자연스럽다. 반대로 조직 안에 이미 한 번 이상 검증되어 다들 베껴 쓰고 있는 프로젝트가 있다면, 그 검증된 결과물을 존중해 승격 경로로 정식화하는 편이 더 안전하고 효율적이다. 두 경로 모두 결국 같은 templates/co-<name>/ 형태로 수렴한다는 점에서, 이는 "어떤 산으로 오를 것인가"의 문제이지 "다른 산에 도착하는가"의 문제는 아니다.

라이선스 — AGPL-3.0 상속

variant 템플릿으로 무엇을 만들든 라이선스는 따라온다. ai-workspace 루트는 AGPL-3.0을 쓰며, 라이선스 롤아웃 정책(2026-08)에 따라 루트의 AGPL-3.0 전문이 모든 variant 템플릿의 LICENSE 파일로 그대로 배포된다. 즉, 어떤 경로로 만든 variant 프로젝트든 태어날 때부터 AGPL-3.0을 상속받는다.

• 템플릿의 LICENSE는 표준 AGPL-3.0 전문이며, 프로젝트별로 임의 수정하지 않는다
• upgrade-project.ts와 승격 파이프라인은 LICENSE를 상위 표준과 동일하게 유지·전파한다 — 프로젝트에서 삭제해도 다음 업그레이드 때 복원된다
• 사내 비공개 사용은 자유롭지만, 네트워크 서비스로 제공하면 소스코드 공개 의무(AGPL 조항 13)가 발생한다. 외부 배포·상용 라이선스가 필요하면 별도 협의가 필요하다