[3편] 그래서 30분만 열어보기로 했습니다
카테고리: AI 기반 개발 / 개발 방법론 태그: harness, 도구평가, AI에이전트, QA, 경계면버그, 1인개발 시리즈: 도구 열 개를 정리하고 방법론 하나를 남겼다 (3/8)
열 개를 깐 사람의 반성
1편에서 세어보니 AI 도구가 열 개였습니다. 2편에서는 그중 두 개를 같은 거라고 착각하고 있었다는 걸 알았습니다.
여기까지 오니 문제가 명확해졌습니다.
저한테는 도구를 판단하는 기준이 없었습니다.
"좋다더라" → 설치 → 튜토리얼 따라하기 → 프로젝트에 적용 시도 → 기존 구조랑 충돌 → 며칠 씨름 → 원상복구 → 피로감
이 사이클을 열 번 돌았습니다. 열한 번째를 돌기 전에 규칙을 만들었습니다.
30분 규칙
1. 격리 설치 기존 프로젝트를 절대 안 건드리는 별도 경로에 푼다
2. 30분 타이머 딱 30분만 본다. 그 이상 안 본다
3. 질문 하나 "내 개발 루프에 없는 걸 주는가?"
4. 판정
- 준다 → 그 부분'만' 뜯어온다. 통째로 안 가져온다
- 안 준다 → 기각. 기각 사유 한 줄만 기록으로 남긴다핵심은 질문이 딱 하나라는 점입니다.
"이 도구가 좋은가?"가 아닙니다. 좋은 도구는 세상에 널렸습니다. "내가 지금 놓치고 있는 걸 이게 메워주는가?" 만 봅니다.
이렇게 물으면 답이 빨리 나옵니다. 내가 뭘 놓치는지를 알고 있어야 답할 수 있고, 모르면 도구 문제가 아니라 내 문제라는 게 바로 드러나거든요.
이 규칙을 처음 적용한 대상이 harness였습니다.
harness가 하려는 일
SKILL.md를 열면 이런 구조가 나옵니다.
프로젝트/
├── .claude/agents/ ← 누가 하는가 (에이전트 정의)
│ ├── analyst.md
│ ├── builder.md
│ └── qa.md
└── .claude/skills/ ← 어떻게 하는가 (스킬 정의)
├── orchestrator/ ← 누가 언제 어떤 순서로
└── content-writer/핵심 발상은 이겁니다.
에이전트는 "누가"를 담고, 스킬은 "어떻게"를 담는다.
분석 담당, 구현 담당, QA 담당을 각각 별도 파일로 정의하고, 오케스트레이터가 이들을 팀으로 묶습니다. 팀원끼리 메시지를 주고받고, 의견이 충돌하면 토론하고, 빠진 게 있으면 서로 보완합니다.
문서에 이런 표가 있습니다.
| 작업 규모 | 권장 팀원 수 | 팀원당 작업 수 |
|---|---|---|
| 소규모 (5~10개 작업) | 2~3명 | 3~5개 |
| 중규모 (10~20개 작업) | 3~5명 | 4~6개 |
| 대규모 (20개+ 작업) | 5~7명 | 4~5개 |
그리고 아래에 이런 문장이 붙어 있습니다.
"팀원이 많을수록 조율 오버헤드가 커진다. 3명의 집중된 팀원이 5명의 산만한 팀원보다 낫다."
읽으면서 좀 웃었습니다. 사람 조직이랑 똑같습니다.
30분 뒤의 판정: 기각
harness의 심장은 에이전트 팀입니다. 문서에도 못 박혀 있습니다.
"에이전트 팀이 최우선 기본값이다. 2개 이상의 에이전트가 협업할 때는 반드시 에이전트 팀을 먼저 검토한다."
훌륭한 설계입니다. 그런데 제 상황에는 과했습니다.
| harness가 전제하는 상황 | 제 상황 |
|---|---|
| 작업 20개 이상, 팀원 5~7명 | 혼자, 한 번에 파일 2~3개 |
| 병렬 실행으로 시간 단축 필요 | 병렬로 돌려도 검토는 결국 제가 함 |
| 산출물이 커서 사람이 다 못 봄 | 제가 다 봐야 안심됨 |
| 에이전트끼리 토론해 품질 상승 | 토론 로그 읽는 시간이 더 듦 |
마지막이 결정적이었습니다.
에이전트 다섯이 서로 메시지를 주고받으면 그 로그를 누가 읽습니까. 결국 제가 읽습니다. 그러면 일이 줄어든 게 아니라 읽을 게 늘어난 겁니다.
1인 운영에서 조율 오버헤드는 전부 제 시간입니다.
대신 세 가지를 가져왔습니다
기각은 했지만, 그 안에 있던 관점 세 개는 그 자리에서 뜯어왔습니다. 전부 제가 실제로 두 번 당한 지점이었기 때문입니다.
이런 일이 있었거든요.
문법 검사 전건 통과 ✅
렌더링 전건 통과 ✅
색상 하드코딩 0건 ✅
────────────────────
화면 열어봄 ❌ 깨져 있음전부 통과했는데 화면이 깨졌습니다. 그것도 두 번이나 그랬습니다. 두 번째로 깨졌을 때 든 생각이 이거였습니다.
"검사를 안 한 게 아니라, 검사하는 눈이 하나뿐이었구나."
① 역할별 렌즈 — 혼자여도 관점은 나눈다
혼자 개발하면 코드 짜기 → 문법 검사 → 돌려보기 → 완료 순으로 갑니다. 네 단계 전부 "만든 사람의 눈" 입니다.
만든 사람은 자기가 의도한 대로 코드를 읽습니다. "여기는 이렇게 동작하겠지"라고 생각하면서 읽으면 진짜 그렇게 읽힙니다.
harness는 이걸 에이전트를 여러 명 두는 걸로 풉니다. 저는 혼자니까, 렌즈를 여러 개 끼기로 했습니다.
| 렌즈 | 이 렌즈로 볼 때 던지는 질문 |
|---|---|
| 🔧 개발 | 요청한 게 진짜 구현됐나? 로직이 맞나? |
| 🔍 QA | 경계면이 맞나? 엣지 케이스는? 화면을 눈으로 봤나? |
| 🛡️ 보안 | 키가 새나? 공개 경로에 노출됐나? 인증 우회 가능한가? |
| ✂️ 최적화 | 소스가 쓸데없이 길지 않나? 중복은? 더 단순한 방법은? |
한꺼번에 보면 의미가 없습니다. 하나씩 따로 끼워야 합니다.
같은 코드를 보는데 질문이 달라지면 눈이 달라집니다. "이거 동작하나?"로 볼 때와 "이거 키 새나?"로 볼 때는 정말 다른 게 보입니다.
② 경계면 QA — 버그는 파일 사이에서 난다
이게 세 개 중 제일 값어치 있었습니다.
harness의 QA 가이드에 이런 대목이 있습니다.
"QA의 핵심은 '존재 확인'이 아니라 '경계면 교차 비교'다. API 응답과 프론트 훅을 동시에 읽고 shape을 비교한다."
읽자마자 뜨끔했습니다. 제가 하던 검사가 전부 "존재 확인" 이었거든요.
❌ 제가 하던 것
- 이 파일 있나? → 있음 ✅
- 이 함수 정의됐나? → 됐음 ✅
- 이 상수 선언됐나? → 됐음 ✅
→ "이상 없음"
✅ 해야 했던 것
- 이 파일이 기대하는 값과, 저 파일이 주는 값이 '같나?'이 관점으로 다시 훑었더니 그 자리에서 세 개가 나왔습니다.
사례 1: 설정 화면이 빈 값을 읽던 문제
settings.php → config.php 의 상수를 읽음
config.php → 그 상수 없음
.env → 값이 여기 있었음두 파일 다 문법적으로 완벽합니다. 서로 다른 곳을 보고 있었을 뿐입니다. 파일 단위로 검사하면 절대 안 걸립니다.
사례 2: 테마 하나가 라우팅에서 빠진 문제
themes/ 폴더 → pro, shop, startup, home (4개)
index.php whitelist → pro, shop, home (startup 없음)둘 다 멀쩡합니다. 목록이 안 맞았을 뿐입니다.
startup 테마를 쓰는 순간에만 터집니다.
사례 3: 저장이 조용히 실패하던 문제
프론트 → 세션키 이름 'csrf'
백엔드 → 세션키 이름 'csrf_token'이름 하나 다릅니다. 그게 전부입니다.
③ 최적화 관점 — "돌아간다"와 "잘 만들었다"는 다르다
세 번째는 좀 부끄럽습니다.
제 완료 조건에는 문법·동작·DB·보안·문서가 있었는데, "코드가 지저분하지 않은가"라는 항목이 아예 없었습니다.
그래서 돌아가긴 하는데 같은 로직이 세 군데 복사돼 있고, 안 쓰는 함수가 남아 있고, 20줄로 될 걸 80줄로 짜놓은 파일이 쌓였습니다.
전부 "완료 조건은 통과한" 코드입니다. 조건에 그 항목이 없었으니까요.
체크리스트에 없는 건 안 합니다. 사람은 원래 그렇습니다. "당연히 신경 써야지" 하는 것들이 실제로는 제일 잘 빠집니다.
정리하면
| harness 요소 | 판정 | 이유 |
|---|---|---|
| 역할별 렌즈 | ✅ 흡수 | 에이전트 없이 혼자서도 씀 |
| 경계면 교차 QA | ✅ 흡수 | 즉시 버그 3건 적발 |
| 최적화 관점 | ✅ 흡수 | 완료 조건에 아예 없던 항목 |
| 에이전트 팀 | ❌ 기각 | 1인 운영에 조율 오버헤드 과다 |
| 오케스트레이터 | ❌ 기각 | 조율할 팀이 없음 |
.claude/agents/ 체계 |
❌ 기각 | 에이전트를 안 씀 |
| 팀 크기 가이드 | ❌ 기각 | 팀원이 저 하나 |
| 단계적 정보 공개 | 🔶 보류 | 개념은 좋음. 나중에 재검토 |
8개 중 3개. 이 비율이 정상이라고 봅니다.
10개 중 10개를 가져와야 할 것 같으면, 그건 도구가 좋은 게 아니라 내가 방법론이 없다는 뜻입니다.
남는 이야기
첫째, "좋은 도구인가"는 잘못된 질문입니다.
물어야 할 건 "내가 지금 놓치고 있는 걸 이게 메워주는가" 입니다. 이 질문에 답하려면 내가 뭘 놓치는지를 먼저 알아야 하고, 그걸 모르면 어떤 도구를 깔아도 소용없습니다. 열 개 깔아본 사람의 말입니다.
둘째, 도구가 아니라 관점을 가져오세요.
경계면 QA는 설치할 게 없습니다. 명령어도 없습니다. "양쪽이 같은 걸 기대하는가를 본다" 는 문장 하나입니다. 그런데 그 문장 하나가 버그 세 개를 잡았습니다.
도구는 버전이 올라가고 유지보수가 끊기지만, 관점은 안 낡습니다.
셋째, 기각도 자산입니다.
"1인 운영에 조율 오버헤드가 과해서 안 맞았다." 이 한 줄을 남겨두면 6개월 뒤 비슷한 도구를 볼 때 30분이 5분으로 줄어듭니다.
버린 것도 기록해야 합니다. 안 하면 6개월 뒤에 똑같이 30분을 씁니다.
이전 편: [2편] harness와 Hermes를 같은 거라고 믿었습니다 다음 편: [4편] 공식 하나를 세 군데에 복사했다가 전부 틀렸습니다
이 글은 실제 도구 평가와 그 결과 적발된 버그의 기록입니다. 흡수 3건 · 기각 4건 · 보류 1건 · 즉시 적발된 경계면 버그 3건
댓글 0