Claude Code를 실무에 붙이려면 모델이 아니라 하네스를 설계해야 한다

같은 Claude 모델을 두고도 어느 날은 멀쩡한 패치를 만들어내고, 어느 날은 엉뚱한 파일을 고친 채 “완료했다”고 내미는 경험이 있을 것이다. 이 차이를 모델 탓으로 돌리기 쉽지만, 실제로는 모델이 일하는 환경, 곧 하네스(Harness)가 결과를 가른다. 모델이 똑같아도 컨텍스트가 흐리면 엉뚱한 파일을…

하네스 엔지니어링은 새로운 기술이 아니라 환경 설계의 다른 이름이다

같은 모델에게 같은 작업을 시켰는데 결과가 완전히 다르게 나온 경험이 있을 것이다. 어떤 날은 멀쩡한 코드를 만들어내고, 어떤 날은 작동하지 않는 결과물을 자신 있게 내민다. 이 차이를 모델 탓으로 돌리기 쉽지만, 최근에는 다른 결론이 자리 잡고 있다. 모델이 아니라 모델이…

AI에게 큰 프로젝트를 통째로 맡기지 마라

로드맵 + Shrimp Task Manager 워크플로우 AI에게 “쇼핑몰 만들어줘”, “인스타그램 같은 SNS 만들어줘” 한마디로 통째로 던져본 사람이라면 결과가 만족스럽지 않았을 것이다. 똑똑한 작업 관리 도구를 붙여도 마찬가지다. 큰 단위는 사람이 직접 로드맵으로 쪼개고, 세부 작업만 Shrimp Task Manager에 위임하는 분업이…

Claude Code 프로젝트의 첫 단추는 MVP PRD다

n개월 동안 견적서 발행 웹을 만들었다. 이메일 자동 발송, 다양한 템플릿, 클라이언트 댓글, 승인·거절, 결제 연동까지 모두 넣었다. 클라이언트에게 보여주자 한 마디가 돌아온다. “그냥 카카오톡으로 보내는 게 편한데요.” 스타트업이 실패하는 가장 큰 이유는 시장이 원하지 않는 제품을 만들었기 때문이다. Claude…

Claude Code 훅은 LLM이 가끔 잊는 일을 결정론으로 보장한다

같은 작업을 두 번 시켰는데 결과가 다르게 나온 적이 있을 것이다. Claude에게 버그를 고쳐 달라고 했더니 어느 날은 테스트까지 돌리지만 다음 날은 코드만 수정하고 끝낸다. 이 차이는 모델의 잘못이 아니라 LLM이 본질적으로 확률 기반으로 다음 토큰을 고르기 때문이다. 그러나 실제…

서브에이전트는 메인 컨텍스트를 지키는 전문가 시스템이다

오전에는 새 기능을 만들고, 오후에는 코드 리뷰를 하고, 저녁에는 보안 점검을, 밤늦게는 테스트를 돌린다. 각각의 작업은 서로 다른 전문 지식을 요구한다. 인테리어를 한 사람이 디자인부터 전기, 타일까지 모두 맡으면 어느 하나도 제대로 끝나지 않듯, Claude Code에 모든 관점을 동시에 요구하면…

커스텀 명령어는 자주 쓰는 프롬프트를 슬래시 한 줄로 압축한다

같은 프롬프트를 매일 반복해서 붙여 넣고 있다면 그 프롬프트는 이미 자동화 대상이다. Claude Code는 반복 프롬프트를 슬래시 명령어 한 줄로 줄여 주는 커스텀 명령어 기능을 제공한다. 마크다운 파일 하나만 만들면 끝난다. 이 글에서는 커스텀 명령어의 기본 구조, 프로젝트와 사용자 단위의…

웹 에디터와 이미지 저장 위치는 서비스 출시 전에 결정한다

상용 서비스를 목표로 바이브 코딩을 진행하다 보면, 가장 가볍게 다뤄지는데 가장 큰 비용을 만드는 결정이 두 개 있다. 웹 에디터를 어떻게 만들 것인가, 그리고 게시물의 이미지·영상을 어디에 저장할 것인가다. 결론부터 말하면 세 가지를 출시 전에 결정해야 한다. 에디터 코드의 분리…

Claude Code로 PHP 프로젝트를 Java로 옮겨보았다

PHP(Laravel) 기반 레거시 API 서버를 Java(Spring Boot)로 옮기는 작업을 Claude Code와 함께 진행한 기록이다 결론부터 말하면 세 가지가 가장 큰 차이를 만들었다. 작업을 한 번에 다 맡기지 않고 단계별로 쪼갠 것, plan.md와 handoff.md를 세션 간 워킹 메모리처럼 운영한 것, PHP와 Java를 동시에…