[Part 6] 회고와 다음 단계

시리즈 목차

개발 요약

빈 폴더에서 시작해 2주 만에 배포까지 완료했다. 물론 기능이 완벽한 건 아니고, 지금도 계속 개선 중이다.

효과가 있었던 것

1. UX 리서치 → 디자인 의사결정

비슷한 서비스를 조사하고, UI/UX를 분석하고, HTML 목업으로 선택지를 만들어 비교하는 플로우가 효과적이었다.

디자이너 없이 혼자 개발하면 **“이게 좋은 디자인인가?”**라는 확신이 없다. 리서치 에이전트가 경쟁 서비스를 분석하고, 목업을 만들어 비교할 수 있게 해주니 디자인 의사결정이 훨씬 명확해졌다.

2. QA 에이전트의 병렬 테스트

기능을 구현하고 나면 qa-agent를 호출해서 단위 테스트, E2E 테스트, 정적 분석을 병렬로 돌렸다.

혼자 개발하면 테스트를 대충 하기 쉬운데, 에이전트가 체계적으로 검증해주니 내가 미처 생각하지 못한 엣지 케이스를 잡아낼 수 있었다.

특히 E2E 테스트에서 “빈 옵션 선택 시 다운로드 버튼이 활성화되는” 같은 버그를 사전에 잡아낸 게 몇 번 있었다.

3. PR 생성 스킬의 크로스체크

/create-pr 스킬을 만들 때 “검증을 진행했는지” 확인하는 단계를 넣었다.

혼자 개발하면 “이 정도면 됐겠지”하고 PR을 올리기 쉬운데, 스킬이 한 번 더 물어보니 마지막 점검을 하게 됐다. 덕분에 검증 없이 올라가는 PR이 줄었다.

4. 의사결정의 기록 (ADR)

기술적 결정을 ADR로 기록하니 **“왜 이렇게 했지?”**라는 질문에 바로 답할 수 있다.

1인 개발이라 나중에 내가 다시 코드를 봐도 결정의 맥락을 기억하기 어려운데, ADR이 있으니 당시 왜 그런 선택을 했는지 바로 확인할 수 있다.

기대와 달랐던 것

컨벤션 없으면 코드 스타일 제각각

AI가 알아서 일관된 코드를 작성할 줄 알았다. 그게 아니었다.

컨벤션을 명시하지 않으면 비슷한 로직도 매번 다른 스타일로 작성한다. 어떤 파일은 function 선언, 어떤 파일은 화살표 함수. 어떤 컴포넌트는 인라인 스타일, 어떤 컴포넌트는 Tailwind만.

나중에 이걸 통일하느라 시간이 많이 들었다. 컨벤션은 처음부터 세부적으로 정의해야 한다는 교훈을 얻었다.

에이전트/스킬이 항상 의도대로 동작하지 않음

역할을 명확히 정의해도 가끔 의도와 다르게 동작한다.

• 간단한 검사를 요청했는데 전체 분석을 시작하거나
• 복잡한 작업을 요청했는데 표면적인 답변만 돌아오거나

초기보다는 많이 개선됐지만, 100% 의도대로 동작하지는 않는다. description을 더 다듬고, 역할 구분을 더 명확히 해야 할 것 같다.

다음 프로젝트에 적용한다면

달리 할 것

필요한 것만 명확히 정의하고 시작

이번에는 “나중에 필요할 것 같은” 에이전트와 스킬을 미리 많이 만들어뒀다. 생각나는 대로 추가했다.

다음에는 실제로 필요한 것만 정의하고 시작할 것이다. 새로운 기능이 필요하면 그때 추가하는 게 낫다.

컨벤션을 먼저 세부적으로 정의

대략적인 컨벤션만 정의하고 시작했다가 코드 스타일이 뒤죽박죽이 됐다.

다음에는 첫 코드를 작성하기 전에 컨벤션을 세부적으로 정의할 것이다. 함수 선언 방식, 스타일링 규칙, 네이밍 규칙 등.

재사용할 것

QA 에이전트 구조

qa-agent가 총괄하고, unit-tester, e2e-tester, static-analyzer가 병렬로 동작하는 구조는 다른 프로젝트에도 그대로 적용할 수 있다.

테스트 프레임워크만 바꾸면 된다. (Vitest → Jest, Playwright → Cypress 등)

PR 생성 스킬

커밋 분석 → 크로스체크 → PR 생성 플로우는 어떤 프로젝트에서도 유용하다. 템플릿만 프로젝트에 맞게 수정하면 된다.

ADR 구조

의사결정을 기록하는 구조는 프로젝트와 무관하게 재사용 가능하다. 템플릿과 폴더 구조를 그대로 가져갈 것이다.

새로 만들 것

리서치 관련 에이전트/스킬 정리

market-intelligence, business-analyst, strategy-planner, /research 스킬이 기능이 겹치는 부분이 있다.

다음 프로젝트에서는 역할을 더 명확히 구분하거나 통합할 것이다.

하네스 시스템의 본질

6부에 걸쳐 하네스 시스템을 다뤘다. 마지막으로 정리하면:

하네스는 AI를 프로젝트에 맞게 튜닝하는 시스템이다.

• CLAUDE.md로 맥락을 준다
• 에이전트로 전문성을 부여한다
• 스킬로 반복 작업을 자동화한다
• 컨벤션으로 일관성을 보장한다
• ADR로 의사결정을 기록한다

하네스가 잘 갖춰지면 AI가 내 프로젝트를 이해하는 팀원처럼 동작한다. 혼자 개발해도 코드 리뷰, QA, 의사결정 논의를 할 수 있다.

물론 완벽하지는 않다. 의도와 다르게 동작하는 경우도 있고, 컨벤션을 안 지키는 경우도 있다. 하지만 없는 것보다 훨씬 낫다.

마무리

ConfigDeck은 configdeck.dev에서 사용해볼 수 있다.

이 시리즈가 Claude Code 하네스 시스템에 관심 있는 분들에게 도움이 되길 바란다. 하네스를 구축하면서 겪은 시행착오와 해결 과정이 비슷한 시도를 하는 분들에게 참고가 됐으면 좋겠다.