AI 에이전트 하네스 개발기 #1 — 20개 스택 × 3개 에이전트, 프로젝트 스캐폴더부터

새 프로젝트를 시작할 때마다 반복되는 작업이 있다. 보일러플레이트 생성, 린트 설정, 테스트 프레임워크 세팅, Docker 구성, 그리고 최근에는 AI 코딩 에이전트의 룰 파일까지. 팀에서 이걸 매번 수동으로 하다 보니 프로젝트마다 설정이 제각각이고, 에이전트 품질도 들쭉날쭉했다. 이 전체를 한 번의 CLI 실행으로 끝내는 도구를 만들기로 했다.

“하네스”라는 이름을 붙였지만, 아직은 하네스의 기반인 스캐폴더 단계다. 에이전트를 실제로 제어하는 장치(커맨드, 품질 게이트, 가드레일)는 #2에서 다룬다.

무엇을 만들었나

create-harness라는 CLI 도구다. 실행하면 인터랙티브 프롬프트가 뜨고, 선택한 옵션에 맞게 프로젝트 전체가 세팅된다.

20개 스택 — Next.js(App/Pages), React, Vue, Nuxt, SvelteKit, Angular, Remix / Go(Gin/Fiber), Java(Spring Boot), Python(FastAPI/Django), Node(Express/NestJS), Rust(Axum) / Solidity(Hardhat/Foundry), Solana(Anchor), Move(Sui)
3개 AI 에이전트 — Claude Code, Gemini CLI, OpenAI Codex CLI
모노레포 (Turborepo + 공유 패키지) / 폴리레포
스택별 세부 옵션 — 아키텍처(FSD, Clean, Layered, DDD 등), 패키지 매니저, 린트, 테스트, ORM, DB, API 스타일, API 문서화, 네이밍 규칙 등
부가 기능 — Docker, Graphify Knowledge Graph, README/.env.example 동적 생성, 의존성 자동 설치, 아키텍처 폴더 구조 생성

선택 플로우는 카테고리(Frontend/Backend/Blockchain/Mobile)를 먼저 고르고, 그 안에서 스택을 선택하는 방식으로 만들었다. 스택이 20개이고 카테고리별로 묶어야 선택이 편하다.

핵심 설계 결정

SKILL.md 오픈 스탠다드

처음에는 Claude Code에만 skills를 넣으려 했다. 리서치해보니 Agent Skills라는 오픈 스탠다드가 있었고, Claude Code, Gemini CLI, Codex CLI가 전부 같은 SKILL.md 포맷을 지원하고 있었다. 경로만 다를 뿐 파일 하나로 3개 에이전트를 커버할 수 있었다.

.claude/skills/code-review/SKILL.md    # Claude Code
.gemini/skills/code-review/SKILL.md    # Gemini CLI
.codex/skills/code-review/SKILL.md     # Codex CLI

rules는 짧게, skills는 길게

에이전트의 rules 파일은 매 대화마다 항상 로드되고, skills는 관련 작업할 때만 로드된다. 보안 체크리스트 같은 긴 내용을 rules에 넣으면 Go 백엔드 작업할 때도 Solidity SWC 37개 항목이 로드되어 토큰을 낭비한다.

그래서 rules에서 보안 파일을 빼고, 같은 내용을 skills에 넣었다.### 블록체인 보안 — 체인별 체크리스트

Solidity의 SWC Registry 37개 항목을 전부 반영하고 나서, 다른 체인도 이런 게 있는지 찾아봤다. 있었다.

체인	출처	주요 항목
Solidity	SWC Registry	reentrancy, overflow, delegatecall 등 37개
Solana	Sealevel Attacks	signer check, PDA collision, CPI 등
Move	Hacken Checklist	capability, resource leak, flash loan 등

블록체인 스택을 선택하면 해당 체인의 보안 체크리스트가 에이전트에 자동 세팅된다.

시행착오

CLI가 execSync에서 안 돌아간다

프레임워크 공식 CLI(create-next-app, sv create, npm create astro 등)를 execSync로 실행하는 방식을 선택했는데, 상당수가 인터랙티브 프롬프트를 띄우거나 TTY를 감지해서 stdio: 'pipe' 모드에서 실패했다. Astro, SolidStart, Qwik, Angular 등이 해당.

결국 이런 스택들은 전부 수동 보일러플레이트 생성으로 fallback 처리했다. CLI가 되면 좋고, 안 되면 직접 package.json + 엔트리 파일 + 설정 파일을 생성하는 방식이다.

Docker — 끝없는 엣지 케이스

Docker 테스트에서 쏟아진 문제들이 압도적이었다.

pnpm — ERR_PNPM_IGNORED_BUILDS로 exit code 1 반환 → --ignore-scripts 추가
pnpm v10 — supply chain 검증이 lockfile을 거부 → Docker에서 pnpm@9 사용
yarn — yarn v4 + corepack 호환 문제 → Docker에서 npm으로 fallback
SvelteKit — 빌드 출력이 dist가 아니라 build → 전용 Dockerfile
Remix — React Router로 통합됨 → create-react-router 사용
Go — go.sum 없음 → COPY go.sum* 와일드카드 + go mod tidy
Python poetry — lockfile 없이 --frozen 실패 → fallback 처리
Angular — Node 22.22.3+ 요구, node:22-alpine은 22.18.0 → node:lts-alpine 사용

브루트포스 테스트

스택 20개에 패키지 매니저별 조합까지 하면 경우의 수가 방대하다. 수동 테스트로는 감당이 안 돼서 브루트포스 테스트 스크립트를 짰다.

각 케이스마다 프로젝트 생성 → 파일 검증 → Docker 빌드 → 컨테이너 실행 → health check까지 자동으로 돌린다. 전체 한 번 돌리면 시간이 걸리지만, 한 줄 고치고 수동으로 확인하는 것보다는 낫다. pnpm supply chain 문제, Angular Node 버전 요구사항 같은 건 이 테스트 없이는 절대 못 잡았을 것이다.

아직 하네스가 아니다

하네스(harness)의 원래 뜻은 말에 씌우는 마구다. 말이 마음대로 뛰어다니지 못하고, 사람이 원하는 방향으로만 가게 제어하는 장치. 지금까지 만든 건 솔직히 스캐폴더에 가깝다. 룰과 스킬을 깔아줬지만, 에이전트가 안 지켜도 막을 수가 없다.

진짜 하네스가 되려면:

워크플로우 강제 — /commit 하면 lint → test → type-check 통과해야 커밋 가능
품질 게이트 — 검증 실패하면 다음 단계로 못 넘어감
가드레일 — .env, lockfile, 마이그레이션 파일 수정 물리적 차단
복잡도 라우팅 — 작업 규모에 따라 에이전트 모델/행동 자동 조절

룰은 “이렇게 해줘”라고 부탁하는 거고, 하네스는 “이렇게 안 하면 못 넘어가게” 강제하는 거다.

기반(스캐폴더)은 깔았으니, #2에서 진짜 고삐를 만든다.