해커톤에서 3시간은 기능 하나를 겨우 붙일 시간입니다. 스탠퍼드에서 열린 Claude@Stanford Buildathon이 딱 그 길이였습니다. 이런 제약에서는 실력 차이가 코딩 속도로 드러나지 않습니다. 무엇을 만들지 정하는 데 몇 분을 쓰는가, 그리고 그 결정을 도중에 몇 번 뒤집는가에서 갈립니다.
Claude를 쓴 해커톤 우승작들과 에이전트 운영 사례를 모아 보면 겹치는 습관이 있습니다. 대부분은 대회장 밖에서도 그대로 쓸 수 있는 것들입니다.
우승작이 공통으로 버린 것
USC 해커톤 프로젝트 갤러리를 훑어보면 상위권 작품들이 무엇을 만들었는지보다 무엇을 안 만들었는지가 눈에 띕니다. 로그인 화면, 설정 페이지, 대시보드가 없습니다.
| 작품 | 붙든 문제 | 만들지 않은 것 |
|---|---|---|
| Claude Cortex | 고위험 의사결정을 위한 멀티 에이전트 추론 | 범용 어시스턴트 UI |
| Weaver | 희소 오토인코더 기반 신경망 검색 품질 | 검색 서비스 전체 |
| BrainstormAI | 거친 아이디어 → 검증된 로드맵 변환 | 프로젝트 관리 도구 |
세 작품의 설명은 모두 한 문장으로 끝납니다. 이것이 범위를 좁혔다는 가장 확실한 신호입니다. 프로젝트를 한 문장으로 설명하지 못한다면 아직 두 개 이상의 문제를 들고 있는 상태입니다.
코드를 치기 전에 끝내야 하는 두 단계
Claude Code 워크플로우를 다루는 n8n 커뮤니티 글은 순서를 못박습니다.
연구 → 계획 → 구현. 곧장 구현으로 넘어가지 마십시오.
연구 단계에서 확인할 것은 외부 라이브러리의 현재 문서입니다. 모델은 학습 시점 이후의 API 변경을 알지 못합니다. 이름이 바뀐 옵션, 사라진 메서드, 기본값이 달라진 설정을 모른 채 코드를 만들면 그럴듯하지만 돌아가지 않는 결과물이 나옵니다. 더 나쁜 것은 이 오류가 실행 직전까지 드러나지 않는다는 점입니다.
계획 단계에서는 구현 순서와 검증 지점을 미리 적습니다. 이 단계를 건너뛰면 모델이 한 번에 너무 많은 파일을 건드리고, 뭔가 깨졌을 때 어디서부터 잘못됐는지 되짚을 수 없습니다. 계획을 먼저 읽고 고치는 편이 코드를 읽고 고치는 것보다 훨씬 빠릅니다.
에이전트는 챗봇이 아니라 배선입니다
Claude Code 에이전트 운영 규칙에서 반복되는 지적은 에이전트를 대화 상대로 취급하지 말라는 것입니다. 계획하고 실행하고 검증하는 시스템으로 배선해야 합니다.
에이전트의 설명문은 소개글이 아니라 라우팅 키입니다. Claude가 그 문장을 읽고 어떤 에이전트를 부를지 정합니다.
# 호출되지 않는 설명 — 언제 부를지 판단할 근거가 없습니다
description: 도움이 되는 코드 리뷰 어시스턴트입니다
# 호출되는 설명 — 발동 조건이 적혀 있습니다
description: 버그, 스타일 문제, 보안 취약점을 검토할 때 사용합니다서브에이전트를 나누는 이유는 역할 분담이 아니라 컨텍스트 관리입니다. 메인 컨텍스트를 책상이라고 하면 서브에이전트는 옆에 놓인 작업대입니다. 로그 전문을 읽거나 파일 수십 개를 훑는 일을 책상 위에서 하면 정작 필요한 정보가 밀려납니다. 결론만 받아오면 책상은 계속 비어 있습니다.
내 프로젝트로 옮기는 다섯 단계
여기서부터가 실제로 손을 움직이는 부분입니다.
-
한 문장 테스트를 먼저 통과하십시오. 만들려는 것을 “누가 어떤 상황에서 무엇을 할 수 있게 된다”로 적어봅니다. 접속사로 두 문장을 이어 붙이게 된다면 그 접속사 뒤쪽을 잘라냅니다. 잘라낸 부분은 다음 버전의 재료로 남겨두면 됩니다.
-
착수 전 30분을 문서에 쓰십시오. 쓸 라이브러리의 현재 문서에서 진입점 API와 최근 변경 사항만 확인합니다. 이 30분이 아까워 보이지만, 낡은 API로 만들어진 코드를 되돌리는 데 드는 시간이 항상 더 깁니다.
-
계획을 대화가 아니라 파일로 남기십시오. 구현 순서와 각 단계의 완료 조건을 파일에 적습니다. 대화 속 계획은 컨텍스트가 밀리면 사라지지만 파일은 남습니다. 방향이 틀어졌을 때 돌아올 지점이 생깁니다.
-
에이전트 설명문을 발동 조건으로 다시 쓰십시오. 기존 설명에서 “~하는 도우미” 같은 표현을 지우고 “언제 부르는가”로 바꿉니다. 에이전트가 있는데도 호출되지 않는다면 대부분 설명문 문제입니다.
-
검증을 사람이 아니라 명령으로 정의하십시오. “잘 되는지 확인”이 아니라 실행할 명령을 적습니다.
npm run build가 통과하는지, 특정 엔드포인트가 200을 주는지처럼 결과가 갈리는 기준이어야 합니다. 이 기준이 없으면 모델은 자기가 만든 것을 스스로 잘 됐다고 보고합니다.
자주 무너지는 지점
| 증상 | 실제 원인 |
|---|---|
| 범위를 좁혔는데 기능이 계속 늘어납니다 | 처음의 한 문장을 파일에 적어두지 않았습니다 |
| 계획을 세웠는데 결과가 어긋납니다 | ”인증을 구현한다”는 계획이 아니라 목표입니다 |
| 에이전트를 여러 개 만들었는데 체감이 없습니다 | 서로의 결과를 기다리는 작업을 나눴습니다 |
머릿속에만 있는 범위는 반드시 늘어납니다. 계획은 어떤 파일에 무엇을 추가하는지까지 내려와야 계획입니다. 그리고 순차 의존이 있는 작업을 병렬로 쪼개면 컨텍스트만 오갈 뿐 이득이 없습니다.
오늘 할 수 있는 것
지금 진행 중인 프로젝트를 하나 골라 한 문장 테스트를 해보십시오. 문장이 깔끔하게 떨어지지 않는다면, 그 프로젝트가 더디게 느껴지는 이유가 실력이 아니라 범위에 있을 가능성이 큽니다.
3시간짜리 대회가 알려주는 것은 빨리 만드는 법이 아닙니다. 무엇을 만들지 정하는 데 시간을 쓰는 쪽이 결국 더 멀리 간다는 사실입니다.