[Part 4] 하네스 기반 개발 과정

시리즈 목차

개발 순서

ConfigDeck은 일반적인 개발 순서와 다르게 진행했다. 하네스를 먼저 구성하고, 코드는 나중에 작성했다.

일반적인 순서:
기획 → 기술 스택 선정 → 개발 환경 세팅 → 개발

ConfigDeck 순서:
기획 → 하네스 구성 → 기술 스택 논의 → 컨벤션 정의 → 개발

1단계: 빈 폴더에서 시작

4월 2일, 완전히 빈 폴더에서 시작했다. CLAUDE.md도 없었다.

첫 대화는 이랬다:

“개발자용 설정 파일 생성 서비스를 만들려고 해. ESLint, Prettier, TypeScript 같은 설정 파일을 UI로 쉽게 만들 수 있는 웹 서비스야. 이 프로젝트에 맞는 하네스를 같이 구성해보자.”

2단계: 에이전트와 스킬 먼저 정의

코드를 한 줄도 쓰기 전에, 어떤 역할이 필요한지부터 정의했다.

• 설정 파일 스키마를 설계할 전문가 → config-maker
• UI/UX를 설계할 전문가 → ux-designer
• 컴포넌트를 구현할 전문가 → ui-publisher
• 품질을 검증할 전문가 → qa-agent
• 경쟁사를 분석할 전문가 → market-intelligence

이 과정에서 gstack의 구조를 많이 참고했다. 팀 에이전트 형식으로 구성하면 어떨지 영감을 받은 오픈소스다.

3단계: 기술 스택 논의

에이전트 구조가 잡힌 후, 기술 스택을 논의했다. 여기서 중요한 건 에이전트와 함께 논의했다는 점이다.

나: "설정 파일 생성기에 적합한 프레임워크가 뭘까?"

에이전트: "몇 가지 선택지를 분석해볼게요.

1. Next.js — 풀스택, 하지만 이 서비스는 DB가 필요 없음
2. Astro — SSG 우선, 콘텐츠 페이지 JS 0KB
3. SvelteKit — 빠른 런타임, 하지만 SSG 지원이 Astro보다 약함

ConfigDeck은 정적 콘텐츠(설정 파일 설명)와 인터랙티브 UI(생성기)가 공존합니다.
Astro + Svelte 조합을 추천합니다. 정적 페이지는 JS 없이, 생성기만 Svelte로."

이런 논의 결과가 ADR-0002로 기록됐다.

4단계: 컨벤션 정의

기술 스택이 정해지면 컨벤션을 정의했다.

# conventions/coding.md

## TypeScript 규칙
- any 사용 금지
- 함수는 화살표 함수로 작성
- as 타입 단언 지양

## Astro vs Svelte 사용 기준
- 정적 콘텐츠 → Astro 컴포넌트
- 인터랙션 필요 → Svelte 컴포넌트

컨벤션을 먼저 정의해야 에이전트가 일관된 코드를 작성한다. 이걸 나중에 정의하면 코드 스타일이 뒤죽박죽이 된다. (Part 5에서 자세히 다룬다)

5단계: CLAUDE.md 작성

에이전트, 스킬, 컨벤션이 모두 준비된 후에야 CLAUDE.md를 작성했다.

CLAUDE.md는 이 모든 것을 한 곳에서 참조할 수 있게 연결하는 역할을 한다.

# CLAUDE.md

## 프로젝트 개요
ConfigDeck은 개발자용 설정 파일 생성 서비스다.

## 하네스 구조
- 에이전트: `.claude/agents/`
- 스킬: `.claude/skills/`
- 컨벤션: `.claude/conventions/`
- ADR: `.claude/decisions/`

## 에이전트 위임 규칙
| 요청 패턴 | 위임 대상 |
|-----------|-----------|
| "설계해줘" | ux-designer |
| "구현해줘" | ui-publisher |
| "검증해줘" | qa-agent |

HTML 목업으로 디자인 결정

디자인 의사결정에서 특히 효과적이었던 방법이 있다. HTML 파일로 목업을 만들어 브라우저에서 바로 확인하는 것이다.

플로우

1. ux-designer나 market-intelligence가 비슷한 서비스를 조사
2. 조사 결과를 바탕으로 디자인 방향 보고서 작성
3. 보고서를 기반으로 HTML 목업 생성 요청
4. 브라우저에서 목업 확인 후 선택

실제 예시

나: "설정 파일 생성기의 UI를 어떻게 구성하면 좋을지 조사해줘"

market-intelligence: (비슷한 서비스 5개 분석)
"조사 결과:
- gitignore.io: 태그 기반 선택
- tsconfig bases: 프리셋 기반
- prettier playground: 실시간 미리보기

추천: 옵션 선택 + 실시간 미리보기 조합"

나: "이 방향으로 HTML 목업 3가지 안을 만들어줘"

HTML 파일로 만들면 Figma나 디자인 툴 없이도 브라우저에서 바로 확인할 수 있다. 선택지를 눈으로 보고 비교한 뒤 결정하니 디자인 의사결정이 훨씬 명확해졌다.

QA 파이프라인

혼자 개발하면서 가장 도움이 된 건 QA 에이전트였다.

구조

              qa-agent (총괄)
                   │
        ┌──────────┼──────────┐
        ▼          ▼          ▼
   unit-tester  e2e-tester  static-analyzer
    (Vitest)   (Playwright)  (ESLint/TS)

실제 사용 방식

기능 구현이 끝나면 qa-agent를 호출한다.

나: "방금 구현한 ESLint 생성기 기능을 검증해줘"

qa-agent: "세 가지 검증을 병렬로 진행합니다.

1. unit-tester: ESLint 옵션 조합별 생성 결과 테스트
2. e2e-tester: 사용자 플로우 (옵션 선택 → 미리보기 → 다운로드) 테스트
3. static-analyzer: 타입 오류, 린트 위반 검사

[결과]
- 단위 테스트: 12개 통과
- E2E 테스트: 1개 실패 — 빈 옵션 선택 시 다운로드 버튼이 활성화됨
- 정적 분석: 통과

수정 필요: 옵션이 하나도 선택되지 않았을 때 다운로드 버튼 비활성화 로직 추가"

E2E 테스트에서 사용자 시나리오대로 동작하는지 검증하면서, 내가 미처 고려하지 못한 엣지 케이스를 잡아낼 수 있었다.

PR 크로스체크

PR 생성도 스킬로 자동화했는데, 여기에 크로스체크 단계를 넣은 게 효과적이었다.

/create-pr 스킬의 동작

/create-pr master

이 명령어를 실행하면:

1. 커밋 히스토리 분석
2. 변경 파일 확인
3. “검증을 진행했는지” 확인
4. “코드 리뷰가 필요한지” 확인
5. PR 본문 작성
6. PR 생성

3번과 4번이 핵심이다. PR을 만들기 전에 한 번 더 점검할 기회를 준다.

스킬: "PR을 생성하기 전에 확인합니다.

- QA 검증을 진행했나요? (Y/N)
- 추가 코드 리뷰가 필요한가요? (Y/N)

N을 선택하면 먼저 검증을 진행합니다."

혼자 개발하면 “이 정도면 됐겠지”하고 넘어가기 쉬운데, 이 크로스체크 덕분에 마지막에 한 번 더 점검하는 습관이 생겼다.

정리

핵심은 코드보다 하네스를 먼저 구성한다는 것이다. 하네스가 잘 갖춰지면 개발은 에이전트와의 협업으로 진행된다.