Claude Code 1년, 프롬프트보다 하네스를 믿게 되기까지

2026년 상반기가 끝났습니다.

작년 이맘때쯤 Claude Code를 쓰기 시작했으니, 이제 거의 1년이 됐습니다. 올해 1월에는 바이브 코딩 6개월 회고를 썼습니다. 그때의 고민은 꽤 개인적이었습니다.

“AI가 코드를 쓰고 나는 리뷰만 하면 되는 걸까?”

“이러다 내가 멍청해지는 건 아닐까?”

반년이 더 지난 지금은 질문이 조금 달라졌습니다. 이제는 AI가 코드를 쓰는 것 자체가 그렇게 신기하지 않습니다. 대신 다른 질문을 더 자주 하게 됩니다.

“이 작업을 다음에도 반복할 수 있게 만들려면 어떤 구조가 필요할까?”

“AI가 실수하지 않게 하려면 어디까지 시스템으로 막아야 할까?”

“사람이 판단해야 하는 것과 컴퓨터가 결정적으로 검증할 수 있는 것은 어떻게 나눠야 할까?”

이 글은 Claude Code를 1년 가까이 쓰면서, 그리고 2026년 상반기에 여러 도구와 업무 파이프라인을 만들면서 작업 방식이 어떻게 바뀌었는지 정리한 글입니다.

시작은 복붙이었습니다

지금은 이걸 하네스라고 부르지만, 처음부터 그런 걸 만들 생각은 없었습니다. 그때는 어떻게 써야 좋은지에 대한 감도 방법도 없어서, 그냥 프롬프트를 되는대로 길게 썼습니다.

2025년 5월쯤에는 Claude 데스크톱 앱으로 프로젝트 문서를 만들고 있었습니다. 머릿속에 있던 아이디어를 설명하고, 기획 문서를 작성하고, 설계 문서를 정리했습니다. Claude가 글을 잘 쓴다는 이야기를 듣고 시작했는데, 실제로 도움이 많이 됐습니다. 지나고 보면 글보다 코딩에 더 잘 맞는 도구였지만, 그건 나중에야 알게 됐습니다.

문제는 방식이었습니다.

필요한 내용을 복사해서 붙여넣고, 컨텍스트가 길어지면 새 채팅을 열고, 다시 설명하고, 또 붙여넣었습니다. 프로젝트 폴더 안의 문서를 그대로 읽는 것이 아니라, 사람이 필요한 조각을 골라 채팅창 안으로 옮겨야 했습니다.

그러다 2025년 6월쯤 Claude Code를 쓰기 시작했습니다.

경험이 완전히 달라졌습니다. 프로젝트 경로를 기준으로 파일을 읽고, 수정하고, 문서를 다시 쓰고, 코드까지 고칠 수 있었습니다. 컨텍스트가 길어져도 자동 요약으로 이어갈 수 있었습니다. 그때는 단순히 “훨씬 빠르다”고 느꼈습니다.

하지만 빠르다는 것은 좋은 일만은 아니었습니다.

경제지표 대시보드를 만들면서 그걸 처음 크게 느꼈습니다. 처음에는 문서에 맞춰 비교적 단순한 구조로 시작했습니다. 그런데 Claude Code로 개발 속도가 올라가자 기능을 계속 붙일 수 있을 것 같았습니다. 관리자 화면도 만들고, 동적 지표 관리도 넣고, 인증과 구독과 로그도 붙일 수 있을 것 같았습니다.

가능했습니다.

그런데 몇 달 뒤 보니 문서와 코드는 서로 다른 시스템을 설명하고 있었습니다. AI가 못해서 생긴 문제가 아니었습니다. 오히려 AI가 빨리 만들어주기 때문에, 구조가 빨리 바뀌고 복잡도도 빨리 늘어났습니다.

이때부터 생각이 조금 바뀌었습니다.

AI가 빠르게 만드는 것만으로는 충분하지 않았습니다. 빠르게 만든 결과가 처음 의도한 구조를 유지하는지, 문서와 맞는지, 이전 결정과 충돌하지 않는지 확인해야 했습니다.

생성된 것과 완료된 것은 달랐습니다

그 다음으로 오래 붙잡았던 프로젝트는 학습 콘텐츠 생성 파이프라인이었습니다.

처음에는 간단하게 생각했습니다. 학습 콘텐츠는 Markdown으로 작성할 수 있고, Markdown은 LLM이 잘 생성하니까, AI에게 콘텐츠를 쓰게 하면 될 것 같았습니다.

실제로 생성은 잘 됐습니다.

하지만 생성된 파일이 곧 사용할 수 있는 콘텐츠는 아니었습니다.

그 Markdown은 단순한 글이 아니었습니다. 앱의 WebView가 그 Markdown을 파싱해서 개요, 핵심 개념, 난이도별 탭, 시각화 컴포넌트, 퀴즈 UI로 렌더링했습니다. 어떤 섹션이 빠지면 UI가 깨지고, 퀴즈 형식이 맞지 않으면 채점이 안 되고, 시각화 메타데이터가 틀리면 컴포넌트가 렌더링되지 않았습니다.

처음에는 프롬프트를 더 자세히 쓰면 해결될 것 같았습니다. 자연어 가이드 문서를 만들고, “이 규칙을 지켜라”라고 지시했습니다. 에이전트도 여러 개로 나눴습니다. 개요를 쓰는 에이전트, 핵심 개념을 쓰는 에이전트, 시각화를 쓰는 에이전트, 퀴즈를 쓰는 에이전트, 마지막에 검토하는 에이전트.

그래도 충분하지 않았습니다.

에이전트를 나누는 것만으로는 일정한 Markdown이 나오지 않았습니다. 어떤 규칙은 LLM에게 맡기면 안 되는 것이었습니다. 필수 섹션이 있는지, Easy/Normal/Expert 설명이 모두 있는지, 퀴즈 개수가 맞는지, 난이도 분포가 맞는지는 사람이 읽어보고 판단할 일이 아니었습니다. 스크립트가 확인할 수 있는 일이었습니다.

그래서 결정 로직과 비결정 로직을 나누기 시작했습니다.

형식, 구조, 필수 필드, 개수 같은 것은 쉘 스크립트로 검사했습니다. 설명이 충분한지, 학습 흐름이 자연스러운지, 개념이 맞는지는 LLM validator가 보게 했습니다.

이 구분이 중요했습니다.

컴퓨터가 확실하게 판단할 수 있는 것은 컴퓨터에게 맡깁니다. 의미를 판단해야 하는 것은 LLM에게 맡깁니다. 둘을 섞지 않습니다.

실패 처리도 바뀌었습니다.

처음에는 실패한 파일을 그대로 고치게 했습니다. 그런데 잘못된 결과 위에서 계속 수정하다 보니 이전 오류가 남고, 지적받지 않은 부분까지 바뀌고, 문맥이 점점 복잡해졌습니다.

그래서 실패하면 수정하지 않고 되돌렸습니다.

단계 시작 전에 파일을 백업합니다. 에이전트가 작성합니다. 검증합니다. 실패하면 백업으로 되돌립니다. 그리고 실패 이유만 다음 시도에 전달합니다.

파일은 깨끗한 상태로 돌아가지만, 실패 이유는 남습니다.

이 방식이 이후 거의 모든 작업의 기준이 됐습니다. 생성보다 검증. 프롬프트보다 workflow. 리뷰보다 하네스.

HTML보다 작은 언어가 필요했습니다

2025년 연말이 되어도 앞서 이야기한 경제지표 대시보드는 끝내지 못한 상태였습니다. 그동안 파이프라인도 만들고 다른 프로젝트도 여러 개 했고 회사 일에도 잘 썼지만, 정작 처음 계기가 됐던 그 프로젝트만 계속 미뤄져 있었습니다. 그래서 연말에 다시 그 프로젝트를 붙잡고 설계부터 점검하며 개발을 시작했는데, 거기서 화면 기획 문제에 부딪혔습니다.

AI에게 화면을 설명할 때 처음에는 Markdown으로 ASCII 스케치를 만들었습니다. 조금 더 구체적인 그림이 필요하면 SVG로 그리거나 HTML로 시안을 만들었습니다.

그런데 이 방식도 애매했습니다.

Markdown ASCII는 해석 여지가 컸습니다. SVG나 HTML은 더 구체적이지만, 간단히 만들면 스케치 수준이고, 자세히 만들면 거의 구현 코드가 됐습니다. 그 정도로 자세히 할 거면 React 코드를 바로 쓰는 편이 나았습니다. 게다가 HTML이나 SVG는 조금만 구체적으로 그려도 토큰을 많이 잡아먹어서, AI가 매번 생성하기에는 비효율적이었습니다.

필요했던 것은 중간 표현이었습니다.

디자인도 아니고, 구현 코드도 아니고, 사람이 보고 피드백할 수 있고, AI가 안정적으로 생성할 수 있고, 렌더링해서 확인할 수 있는 표현이 필요했습니다.

머메이드로 다이어그램을 그리듯, 텍스트로 와이어프레임을 그릴 수 있으면 좋겠다고 생각했습니다.

그래서 Wireweave를 만들었습니다.

Wireweave는 HTML 대신 쓰는 작은 문법입니다. 다만 사람이 직접 문법을 외워서 쓰기 위한 언어라기보다, AI가 안정적으로 생성하기 쉬운 언어에 가깝습니다. parser, renderer, validator, CLI, SDK, MCP 같은 주변 도구도 같이 만들었습니다.

여기서 다시 같은 패턴이 반복됐습니다.

AI에게 “예쁜 HTML을 만들어줘”라고 말하는 대신, AI가 생성할 수 있는 표현 공간을 제한했습니다. 그리고 그 제한된 공간을 파싱하고, 검증하고, 렌더링할 수 있게 만들었습니다.

이때부터 도구를 만들고, 그 도구로 다시 다른 작업을 하고, 사용하면서 생긴 불편을 다시 도구에 반영하는 흐름이 자연스러워졌습니다.

도구를 만든 뒤 끝나는 것이 아니라, 도구를 쓰면서 다음 도구가 생겼습니다.

기억은 대화창 밖에 있어야 했습니다

Claude Code를 여러 개 동시에 쓰기 시작하면서 또 다른 문제가 생겼습니다.

파일 충돌이 가장 큰 문제는 아니었습니다. 이미 git worktree를 자주 쓰고 있었고, 한 프로젝트를 여러 세션이 동시에 고치기보다 여러 프로젝트를 세션별로 나눠 동시에 진행하는 경우가 더 많았습니다.

진짜 문제는 기억이었습니다.

어느 터미널에서 어떤 프로젝트를 열었는지, 그 세션이 무엇을 했는지, 어디까지 진행했는지, 다음에 무엇을 이어가야 하는지를 계속 기억해야 했습니다.

처음에는 Trello와 연결한 Claude Code 스킬을 만들었습니다. 세션을 시작하면 카드를 만들고, 작업 중간에 기록하고, 끝나면 완료 처리했습니다. 작업 관리라기보다 세션 이력을 남기기 위한 목적이었습니다.

AI-DLC 문서도 활용했습니다. 설계 문서와 작업 로그를 남기고, 다음 세션에서 이어가게 했습니다.

도움은 됐습니다.

하지만 문서는 보장하지 않습니다. LLM이 안 읽을 수 있고, 사람이 동기화하지 않으면 금방 낡습니다. 카드도 마찬가지입니다. 기록은 남지만, Claude Code가 반드시 그 기록을 확인한다는 보장은 없습니다.

그래서 Clawket을 만들었습니다.

Clawket은 단순 TODO 도구가 아니라 Claude Code 작업 상태를 SQLite, daemon, CLI, MCP, hook으로 옮기는 시스템입니다. 세션 시작, prompt 제출, tool 사용 전후, subagent 시작과 종료, stop 시점에 hook이 동작합니다.

AI에게 “잘 기억해”라고 말하지 않습니다.

기억해야 하는 순간을 시스템이 먼저 정의합니다.

이후에는 작업을 대화창 안에만 두지 않는 것이 자연스러워졌습니다. 작업 상태는 DB에 있고, 실행 기록은 run으로 남고, 완료 근거는 evidence로 남습니다. Claude Code 세션은 그 상태를 읽고 작업합니다.

Task만으로는 오래 가지 않았습니다

Clawket으로 plan과 task를 만들 수 있게 됐지만, 그것만으로 큰 작업이 오래 지속되지는 않았습니다.

task는 많아집니다. 중간에 확인해야 합니다. 어떤 task는 취소됩니다. 어떤 task는 더 이상 의미가 없어집니다. 큰 작업에서는 task 목록 자체보다 더 오래 남아야 하는 것이 필요했습니다.

그때 다시 보게 된 것이 Scenario였습니다.

제품은 보통 task 목록으로 이해되지 않습니다. 사용자가 어떤 상황에서 어떤 행동을 했을 때 어떤 결과가 나와야 하는지로 이해됩니다. 그래서 SDI에서는 Given/When/Then 형식의 scenario를 중심에 두고, task는 그 scenario를 만족시키기 위한 실행 산출물로 낮췄습니다.

이것도 특별히 새로운 방법론을 만든 것은 아닙니다. BDD나 AI-DLC에서 쓰던 형식을 가져와서, 제가 쓰는 작업 환경에 맞게 더 강하게 적용해본 것에 가깝습니다.

중요한 변화는 task의 위치였습니다.

예전에는 task가 중심이었습니다. 이제는 scenario가 중심이고, task는 scenario를 만족시키기 위해 그때그때 분해되는 실행 단위가 됐습니다. decision은 왜 그렇게 했는지 남기고, evidence는 정말 그렇게 동작하는지 남깁니다.

AI가 task를 빠르게 처리할수록, task보다 오래 남는 기준이 더 중요해졌습니다.

여기서 구분이 하나 더 생겼습니다. task나 scenario 같은 작업 기록은 언제든 사라져도 되는 휘발성 자산입니다. 정말 오래 남아야 하는 것은 제품의 스펙과 구조, 그리고 그동안 내린 결정 같은 영구적인 진실입니다. 그 영구적인 진실을 한곳에서 읽으려고 SSOT라는 조회 전용 도구를 따로 만들었습니다. 작업 도구가 사라져도 제품이 무엇인지는 그 단일 소스에서 복원할 수 있어야 한다는 생각이었습니다.

2026년 6월에는 업무 자체를 하네스로 만들고 있었습니다

2026년 6월쯤부터는 관심이 조금 더 이동했습니다.

처음에는 AI에게 코드를 잘 쓰게 하고 싶었습니다. 그 다음에는 AI가 쓴 것을 검증하고 싶었습니다. 그 다음에는 여러 세션의 상태를 관리하고 싶었습니다.

최근에는 반복되는 업무 자체를 workflow로 만들고 있습니다.

회사 프로젝트라 구체적인 이름은 생략하겠습니다. 하지만 형태는 분명합니다.

하나는 디자인 시스템 관련 작업이었습니다. React로 된 운영 UI를 정적 HTML/CSS 카탈로그와 contract로 정리하고, AI가 화면을 생성하더라도 token, component contract, page gate를 통과하도록 만들었습니다. 같은 에이전트가 만들고 스스로 합격시키지 않도록 producer와 validator도 나눴습니다.

또 하나는 업무 문서화와 기능 매핑 파이프라인이었습니다. 메뉴를 캡처하고, 기능을 추출하고, 차기 플랫폼의 capability에 매핑하고, 누락된 화면을 다시 찾고, 검증하고, coverage를 집계하는 흐름입니다. 여기서도 핵심은 “AI가 문서를 써준다”가 아니었습니다. 업무를 단계, 상태, 검증, 재시도 루프로 바꾸는 것이었습니다.

배포 업무에서도 비슷한 일이 있었습니다.

고객사마다 쓰는 버전이 다르고, 수정 상황마다 빌드해야 하는 ref가 다르고, 어떤 때는 산출물 전달까지만 가면 되고, 어떤 때는 이미지 빌드와 개발계 반영까지 가야 했습니다. 매번 터미널에서 명령을 조합하고, 어떤 버전이 이미 발행됐는지 확인하고, 다음 rc 번호를 기억하는 일이 번거로웠습니다.

그래서 Agent Deck에 version/ref와 stage를 matrix로 올렸습니다.

배포 스크립트 자체가 중요한 것이 아닙니다. 중요한 것은 사람이 매번 기억하던 반복 판단을 workflow cell로 낮춘 점입니다. 어떤 버전의 어떤 ref를 어느 단계까지 보낼지 선택하면 실행되고, 실행 기록은 run으로 남습니다.

이때 Agent Deck은 배포 UI가 아니라 반복 실행 단위 관리 도구에 가까웠습니다.

그러고 보면 이 Agent Deck의 첫 버전 자체가 지난 글에서 이야기한 7시간짜리 자율 세션에서 나온 것이었습니다.

반년 사이에 달라진 것

1월에 쓴 6개월 회고와 지금을 비교하면, 달라진 점이 보입니다.

그때는 AI를 쓰는 나 자신에 대한 불안이 컸습니다. 지금은 그 불안은 많이 줄었습니다. 대신 작업 환경을 어떻게 설계할지가 더 중요해졌습니다.

반년 전에는 “AI가 잘하는 것은 AI에게 맡기고, 나는 무엇을 해야 하는가”를 생각했습니다.

지금은 조금 더 구체적입니다.

AI가 잘하는 일은 맡깁니다. 하지만 그 일이 들어갈 입력 형식, 실행 순서, 검증 기준, 실패 처리, 상태 저장, 완료 근거는 사람이 설계해야 합니다.

이 흐름을 한 문장으로 줄이면 이렇습니다.

AI를 잘 쓰는 일은 프롬프트를 잘 쓰는 일에서, AI가 일할 수 있는 환경을 설계하는 일로 옮겨가고 있습니다.

저는 이걸 하네스라고 부르는 것이 꽤 적절하다고 느낍니다.

다만 거창한 의미로 쓰고 싶지는 않습니다. 제가 새로운 방법론을 만든 것은 아닙니다. AI-DLC, BDD, 하네스 엔지니어링, Claude Code의 hook과 skill, MCP 같은 이미 있는 개념과 도구를 가져와서, 제가 겪는 문제에 맞게 조합해보고 있는 중입니다.

그 과정에서 반복해서 남은 원칙은 몇 가지입니다.

AI에게 자연어로 규칙을 더 많이 설명하기 전에, 결정적으로 검사할 수 있는 규칙은 코드로 옮깁니다.

생성하는 에이전트와 검증하는 에이전트를 분리합니다.

실패를 예외로 보지 않고 rollback, retry, feedback 루프 안에 넣습니다.

작업 상태는 대화창에 두지 않고 DB나 파일로 외부화합니다.

task보다 오래 남아야 하는 scenario, decision, evidence를 먼저 봅니다.

그리고 반복되는 업무는 사람이 매번 기억하는 절차로 두지 않고 workflow로 만듭니다.

더 많이 만들게 됐지만, 더 조심하게 됐습니다

Claude Code를 쓰기 전에는 “이걸 만들까?”에서 멈춘 일이 많았습니다. 지금은 일단 만들어볼 수 있습니다. 작은 CLI, 스킬, MCP 서버, 데스크톱 앱, 디자인 시스템 도구, 업무 파이프라인까지 이전보다 훨씬 쉽게 시작합니다.

만드는 대상도 이 시기에 넓어졌습니다. 처음엔 대부분 작업을 돕는 도구였고, 그중 로컬 파일과 Claude Code CLI에 붙어야 하는 것들은 Tauri로 데스크톱 앱이 됐습니다 — Clawket과 sdi-plugin은 웹으로 먼저 만든 뒤 감쌌고, 배포에 쓴 Agent Deck은 처음부터 데스크톱 앱 자체를 목표로 했습니다. 그러다 도구를 넘어 클라이언트 앱 자체를 만들게 됐습니다. 모바일은 React Native로 학습 앱(StudyArk)과 게임 앱(game-master)을 만들었고요. LLM 활용이 “작업을 돕는 도구를 짜는 일”에서 “모바일·데스크톱 앱을 직접 개발하는 일”로도 넓어진 시기였습니다.

공개로 만든 것 중 하나는 agent-devtools였습니다. 실행 중인 앱 화면에서 컴포넌트를 집으면 그 코드를 읽고 바로 고치는 인앱 에이전트인데, 사용자가 쓰던 Claude 구독을 그대로 재사용하도록 만들었습니다. 여기서도 핵심은 더 많은 자유가 아니라 경계였습니다. 개발 환경에서만 뜨도록 빌드와 런타임 두 겹으로 막고, 프로덕션 산출물에 코드가 새어 나가지 않는지 스크립트가 매번 검사합니다.

하지만 동시에 더 조심하게 됐습니다.

AI가 빠르게 만들수록, 잘못된 구조도 빠르게 굳어집니다. 문서와 코드가 빨리 어긋나고, 세션 기억과 파일 시스템 상태가 어긋나고, task는 많아지지만 실제 제품 행동과 연결되지 않을 수 있습니다.

그래서 이제는 “얼마나 빨리 만들었는가”보다 “다음에도 같은 방식으로 반복할 수 있는가”를 더 보게 됩니다.

한 번 성공한 작업보다, 다시 돌릴 수 있는 작업이 더 오래 남습니다.

하나의 결과물보다, 그 결과물을 만드는 하네스가 다음 프로젝트로 옮겨갑니다.

올해 상반기에 만든 것들을 돌아보면, 프로젝트 이름은 다 다르지만 비슷한 구조가 반복됩니다. 콘텐츠 생성, 화면 기획 DSL, 세션 상태 관리, scenario 중심 작업, 디자인 시스템 생성, 업무 매핑, 배포 matrix. 겉으로는 다른데 안쪽에서는 비슷한 질문을 하고 있었습니다.

“이 반복을 어떻게 시스템으로 만들 수 있을까?”

마무리

Claude Code 1년을 한 문장으로 정리하면, 처음에는 AI가 코드를 대신 써주는 도구였고, 지금은 작업 환경을 다시 생각하게 만드는 도구가 됐습니다.

AI가 더 똑똑해지는 것도 중요합니다. 좋은 모델은 분명히 차이를 만듭니다. 하지만 지난 1년 동안 더 크게 체감한 것은 모델 바깥의 환경이었습니다. 어떤 파일을 읽게 할지, 어떤 도구를 줄지, 어떤 상태를 남길지, 언제 멈추고 언제 재시도할지, 무엇을 완료로 볼지.

이제는 Claude Code를 켜고 바로 “이거 만들어줘”라고 하기보다, 먼저 생각합니다.

“이 작업은 한 번만 할 일인가, 반복될 일인가?”

“반복된다면 어떤 하네스가 필요할까?”

아마 올해 하반기에도 계속 도구를 만들 것 같습니다. 다만 이제는 도구 자체보다, 그 도구가 어떤 반복 업무를 줄이고 어떤 판단을 시스템으로 옮기는지를 더 보게 될 것 같습니다.

돌아보면 조금 웃깁니다. 이 모든 게 시작된 경제지표 대시보드는 1년이 지난 지금도 완성하지 못했습니다. 다만 반복 작업을 감싸는 파이프라인이 충분히 갖춰지면, 그때는 그 대시보드 자체를 파이프라인으로 자동화해서 만들어보게 되지 않을까 상상합니다.

여러분도 자주 반복하는 AI 작업이 있다면, 프롬프트를 조금 더 다듬기 전에 그 작업을 감싸는 작은 하네스를 먼저 생각해보는 건 어떨까요.