GAIA: Claude Code를 위한 스펙 우선 개발 하네스

누구에게 적합한가

GAIA는 스스로를 "A serious harness for Claude Code", 즉 Claude Code를 위한 진지한 엔지니어링 하네스라고 소개합니다. "코드를 쓰기 전에 먼저 생각하기"를 프로세스로 굳히는 도구입니다. 코드 앞에 스펙을 먼저 쓰고(Specs before code), 모든 커밋에 품질 게이트를 두고, 모든 머지에 Code Audit Team 감사를 더합니다. 다음과 같은 개발자에게 적합합니다.

• Claude Code로 실제 소프트웨어 개발을 하며, 모든 변경에 스펙에 근거한 뒷받침이 먼저 있고 커밋은 검증 가능하며 머지는 감사 가능하기를 바라는 개발자. 한 번의 대화로 검증되지 않은 코드가 만들어지는 방식이 아닙니다.
• 프로세스 제약을 받아들이는 개발자. 커밋 전에 타입 검사, lint, 단위 및 Storybook 테스트, Playwright E2E, 개발 서버 스모크 테스트를 통과해야 하고, 모두 통과해야 통과로 인정됩니다.
• 실행 요건을 충족하는 경우. Node.js >= 22.22.0.

다음의 경우에는 적합하지 않거나 먼저 확인이 필요합니다.

• Claude Code를 사용하지 않는 환경. 공식은 이를 Claude Code의 하네스로만 묘사하며, 다른 agent에서 쓸 수 있는지는 언급하지 않습니다.
• 스펙과 테스트 과정 없이 스크립트만 빠르게 만들고 싶은 경우. 스펙을 먼저 쓰도록 요구하므로 선행 비용이 더 큽니다.
• 범용 채팅이나 순수 글쓰기 보조를 기대하는 경우. 공식 설명은 전부 개발 프로세스 제약에 관한 것이며 다른 용도는 언급하지 않습니다.
• Node.js >= 22.22.0 외에 공식이 다른 환경 제한을 열거하지 않으므로, 시스템 호환성은 확인 전까지는 알 수 없는 것으로 봐야 합니다.

3분 만에 첫 사용 완료하기

권장되는 메인 경로는 단 하나입니다. 먼저 공식 명령으로 프로젝트를 만들고, 그다음 Claude Code 안에서 스펙 작성을 트리거합니다.

전제 조건: 로컬에 Node.js >= 22.22.0이 설치되어 있고 Claude Code를 사용할 수 있어야 합니다.

설치: 터미널에서 실행합니다.

npx create-gaia@latest my-app

공식은 저장소를 clone하거나 fork하는 대신 이 방식으로 프로젝트를 시작할 것을 분명히 요구합니다. 명령의 my-app은 새 프로젝트의 이름입니다. 첫 사용에서는 이 이름을 그대로 두어 기존 디렉터리와 혼동되지 않게 하세요.

작업 트리거: 새로 만든 my-app 디렉터리로 들어가 Claude Code에서 /gaia-spec을 입력합니다. 공식은 이 작업을 소크라테스식 질문(Socratic discovery)을 통해 불변의 SPEC 아티팩트를 작성하는 것으로 설명합니다. 즉, 처음부터 문서를 만들어내는 것이 아니라 요구 사항에 대해 항목별로 묻고, 답을 받은 뒤에 결론을 스펙으로 수렴시킵니다. 부수 효과와 확인 지점: 스펙 아티팩트를 생성하며, 한 번 생성되면 불변(immutable)입니다. 따라서 질문에 답할 때는 요구 사항을 확실히 확인한 뒤 마무리하세요. 첫 사용은 이 새 프로젝트 안에서 진행하고 기존 코드는 건드리지 않는 것이 좋습니다.

성공 신호: 질문이 끝나고 생성된 SPEC 아티팩트를 받았다면 스펙 작성 흐름이 완료된 것입니다. 도중에 전문이 바로 나오지 않고 수렴해 가는 질문이 여러 라운드 이어지는 것으로 보인다면, 그것이 바로 이 작업의 설계입니다. 질문으로 요구 사항을 명확히 하는 방식입니다.

사용 사례

사례 1: 새 프로젝트 착수 전에 요구 사항 고정하기. 상황: 새 프로젝트를 시작하려는데, 구두로 전달한 요구 사항이 여러 대화 라운드에 걸쳐 흐려지고 라운드마다 구현 방향이 달라지는 것이 걱정됩니다. 시작: npx create-gaia@latest my-app으로 만든 프로젝트에서 Claude Code에 /gaia-spec을 요청합니다. 과정과 결과: agent는 소크라테스식 질문으로 요구 사항을 항목별로 명확히 하고 최종적으로 불변의 SPEC 아티팩트를 산출합니다. 스펙 우선이 이 하네스의 동작 방식이므로 이 아티팩트는 이후 코드 작성 전의 일관된 기준이 됩니다. 아티팩트는 불변이며, 생성 전의 질문 단계가 유일한 확인 지점입니다. 답하기 전에 핵심 결정을 정리하세요. SPEC 아티팩트의 파일 이름과 저장 위치는 공식 명기가 없으며, 확인 가능한 끝점은 "불변 아티팩트 생성"이라는 단계입니다.

사례 2: 작은 변경 하나를 커밋하며 커밋 전 품질 게이트 체험하기. 상황: GAIA 프로젝트에서 코드 한 곳을 수정하고 커밋하려 합니다. 시작: 평소 흐름대로 커밋을 한 번 실행합니다. 과정과 결과: 커밋 전에 품질 게이트가 실행됩니다. 타입 검사(Typecheck), lint, 단위 및 Storybook 테스트, Playwright E2E, 개발 서버 스모크 테스트가 모두 통과해야 커밋이 계속되며, 하나라도 통과하지 못하면 커밋을 완료할 수 없습니다. 게이트의 전 과정을 관찰하기 쉽도록 영향이 작은 변경을 고르는 것이 좋습니다. 게이트에는 E2E와 스모크 테스트가 포함되어 실제로 실행되므로, 첫 실행은 보통 게이트 없는 커밋보다 시간이 더 걸리고 로컬 환경에서도 개발 서버를 띄울 수 있어야 합니다. 게이트를 건너뛰는 방법이 있는지는 공식 설명이 없습니다.

사용상 한계

• 실행 환경: 공식이 확인한 요건은 Node.js >= 22.22.0뿐이며, 그 외 시스템 수준의 제한은 제시되지 않았습니다. 사용 전에 환경을 직접 확인하세요.
• 클라이언트 전제: GAIA는 Claude Code를 대상으로 합니다. 다른 agent와 함께 쓸 수 있는지는 공식 설명이 없습니다.
• 부수 효과와 확인 지점: /gaia-spec은 불변의 SPEC 아티팩트를 생성하며, 생성 전에 질문 확인 단계가 있습니다. 커밋으로 촉발되는 게이트는 테스트, E2E, 개발 서버 스모크 테스트를 실제로 실행합니다.
• 게이트 범위: 공식이 나열한 검사 항목은 타입 검사, lint, 단위 및 Storybook 테스트, Playwright E2E, 개발 서버 스모크 테스트입니다. 그 외의 검사가 있는지는 설명되지 않았습니다.
• 샌드박스 제한: 공식은 샌드박스 규칙이 .env 파일, 키와 인증서 파일, 자격 증명 이름의 파일(block reads of .env files, key and certificate files, credential-named files) 읽기를 차단한다고 명시하며, agent가 민감한 자격 증명에 접촉할 기회를 줄입니다.
• 머지 제약: 모든 머지에는 Code Audit Team 감사가 따릅니다. 감사의 구체적인 산출 형식과 소요 시간은 공식 설명이 없습니다.
• 아직 미확인: /gaia-spec 외에 어떤 작업이 있는지, SPEC의 저장 위치, GUI 유무, 지원 언어 범위는 공식 페이지에 모두 없습니다. 프로젝트 내부의 실제 안내를 따르세요.