Harness Engineering — 12장: 빈 파일에서 백만 사용자까지

비전형적 표본 — 프로그래밍 경험 대신 다른 경험을 쌓은 사람

앞선 사례의 주인공들은 Terraform, TDD, ML 파이프라인, 대규모 소프트웨어 개발 경험을 갖고 있었다. 이 장의 저자는 스스로를 그들과 다른 표본으로 제시한다. 수기 코딩 경험이 전혀 없는 상태에서 모든 제품의 첫 줄부터 AI 생성으로 시작했다는 것이다.

A different sample

“코드를 쓰다 그만둔 것”이 아니라 처음부터 쓰지 않았다

원문은 모든 제품을 AI가 생성했다고 서술한다. 이 사례의 의미는 비전문가도 자동으로 성공한다는 주장이 아니라, Harness 설계의 학습 경로가 반드시 전통적 코딩 경력 하나로만 연결되지는 않는다는 점에 있다.

Top 1 App Store 유료 차트 · 원문 서술

1M+ 누적 사용자 · 원문 서술

10K+ DeepSeek 관련 도서 판매 규모 · 원문 표현 “수만 부”

300K+ 공식 계정 + Bilibili 팔로어 · 원문 서술

What this proves — and does not prove

핵심 질문은 “코딩을 모르는가”가 아니라 “어떻게 학습했는가”다

원문은 이 사례가 의미 있는 이유를 Harness Engineering의 진입 장벽과 연결한다. 오랜 프로그래밍 경력이 없더라도 반복적인 AI 협업을 통해 행동 패턴을 관찰하고, 실패를 규칙과 제약과 모듈로 바꾸는 경험을 축적할 수 있다는 주장이다.

경험의 모양은 달라도 경험의 무게까지 사라지는 것은 아니다. 프로그래밍 경험이 없다는 사실은 경험이 없다는 뜻이 아니라, 다른 종류의 반복을 오래 통과했다는 뜻일 수 있다.

빈 CLAUDE.md — 무엇을 쓸지 몰라 그냥 두었다

출발점은 방법론이 아니었다. Claude Code가 프로젝트 루트의 CLAUDE.md를 자동으로 읽는다는 사실은 알고 있었지만, 무엇을 써야 할지 몰라 빈 파일로 두었다. 그 다음부터 AI가 실수하기 시작했다.

Mistake 01

파일을 잘못된 작업공간에 저장

공식 계정 글쓰기 파일을 iOS 개발 폴더에 저장했다. 사람이 다시 옮긴 뒤 저장 위치를 규칙으로 남겼다.

→ 글쓰기 파일은 지정된 글쓰기 디렉터리에 저장

Mistake 02

원하지 않는 Markdown 스타일

굵게, 기울임, 구분선을 지나치게 많이 사용했다. 선호하지 않는 스타일을 한 줄의 규칙으로 추가했다.

→ Markdown 강조 표현을 과도하게 사용하지 않음

Mistake 03

익숙하지 않은 인용부호

저자가 선호하는 인용 표기와 다른 문장부호를 사용했다. 다시 한 줄의 규칙이 생겼다.

→ 선호하는 인용부호 규칙을 명시

“한 번 거슬릴 때마다 한 줄을 추가한다.”

처음부터 완전한 규칙집을 만들지 않는다. 실패가 규칙의 필요성을 증명한 뒤에야 한 줄이 생긴다. 이 방식은 규칙의 근거를 상상에서 실제 경험으로 옮긴다.

규칙이 많아지자 첫 번째 리팩터링이 시작된다

약 3개월 뒤 CLAUDE.md는 수십 줄로 늘었다. 파일 조직, 글쓰기 스타일, 이미지 처리, 앱 개발 규칙이 한데 섞이자 관련 없는 규칙이 서로 다른 작업을 방해하기 시작했다.

ROOT CLAUDE.md = Router 작업 유형을 판단하고 필요한 하위 규칙만 연결한다.

01 · 공식 계정 글쓰기

주제 선정 → 조사 → 작성 → 교정 → 이미지 → 게시의 전용 흐름과 스타일 규칙을 가진다.

03 · 영상 제작

자막 다운로드 → 내용 분석 → 스크립트 → 교정의 별도 흐름을 가진다.

App Development

프로젝트별 아키텍처 규칙과 개발 절차를 하위 CLAUDE.md가 담당한다.

라우터의 핵심 가치는 한 번의 대화에 필요한 규칙만 불러오는 데 있다. 원문은 컨텍스트를 희소 자원으로 본다. 관련 없는 지식을 줄이는 것이 곧 더 많은 지식을 넣는 것만큼 중요한 설계가 된다.

이 구조는 처음부터 multi-agent routing을 공부해서 만든 것이 아니라고 원문은 밝힌다. 파일이 커지자 AI가 헷갈렸고, 헷갈림을 줄이려다 자연스럽게 라우팅 구조에 도달했다. 이론이 실천을 낳은 것이 아니라 실천이 뒤늦게 이론과 같은 모양을 얻었다.

규칙에서 시스템으로 — Advice, Constraint, Capability

CLAUDE.md는 무엇을 해야 하는지 알려줄 수 있지만 실제 실행을 보장하지는 못한다. 원문은 이 한계를 만난 뒤 Hooks와 Skills가 추가되는 과정을 설명한다.

Rules

CLAUDE.md — 조언

무엇을 해야 하고 무엇을 선호하는지 알려준다. 그러나 “편집 전 lint를 실행하라”고 적어도 Agent가 가끔 듣지 않는 문제가 남는다.

스타일 규칙
파일 위치
프로젝트 맥락
작업공간 라우팅

Hooks

Hooks — 강제 제약

핵심 작업 전후에 스크립트를 삽입한다. 파일 편집 전 lint, 코드 생성 후 type check처럼 통과하지 못하면 다음 단계로 넘어가지 못하게 한다.

자동 lint
type check
실행 전후 검증
협상 불가능한 gate

Skills

Skills — 반복 작업의 능력 패키지

이미지 생성·업로드·링크 삽입, Feishu 동기화, Xiaohongshu 편집, 영상 자막 다운로드와 분석처럼 반복해서 설명하던 절차를 하나의 호출 가능한 능력으로 만든다.

필요할 때만 로드
복합 단계를 한 번에 실행
대화의 반복 지시를 제거
재사용 가능한 작업 단위

CLAUDE.md “이렇게 하라”는 조언

≠

Hooks “이 조건 없이는 못 지나간다”는 제약

100+

원문은 현재 100개가 넘는 Skills가 축적되었다고 서술한다. 중요한 점은 숫자가 아니라 모든 Skill이 구체적인 반복 불편에서 태어났다는 점이다. 처음부터 기능 목록을 설계한 것이 아니라, 같은 절차를 여러 번 설명하는 피로가 능력의 경계를 만들었다.

규칙이 행동을 설명하고, Hook이 행동을 강제하며, Skill이 행동을 묶는다. Harness는 문서의 확장이 아니라 문서·제약·실행 능력이 서로 다른 층을 맡는 시스템으로 변한다.

성장의 패턴 — 문제를 해결하면 다음 문제가 모습을 드러낸다

되돌아보면 성장 과정에는 반복되는 리듬이 있었다. AI의 실수에서 규칙이 생기고, 규칙이 많아지면 구조를 다시 나누며, 그 구조가 새로운 한계를 드러내면 다른 계층이 추가된다.

AI가 거슬리게 함실패가 관찰됨

→

규칙 추가재발을 막음

→

규칙 과잉컨텍스트 혼선

→

리팩터링라우팅·모듈화

→

새 문제다음 계층의 필요

STAGE 1 빈 파일 → 규칙

실패가 발생할 때 한 줄씩 추가.

STAGE 2 규칙 → Router

직관은 어디에서 오는가 — 수천 시간의 반복에서 온다

원문은 스스로에게 불편한 질문을 던진다. 왜 이런 판단을 할 수 있게 되었는가. 답은 타고난 시스템 설계 능력이나 방법론 책이 아니라 AI와 협업한 수천 시간 동안 반복해서 행동 패턴을 관찰한 경험이라고 한다.

관찰하게 된 것

코드 문법이 아니라 Agent의 행동을 읽는 법을 배웠다는 서술이다.

언제 일을 대충 끝내려 하는가

언제 hallucination이 나타나는가

언제 부드러운 지시보다 단단한 제약이 필요한가

어떤 표현의 규칙을 실제로 따르는가

Skill을 어느 정도 크기로 묶어야 하는가

말로 설명하기 어려운 이유

많은 결정이 직관으로 내려지기 때문이다. 원문은 직관을 신비한 능력으로 보지 않는다. 시행착오가 반복되고, 반복이 충분히 쌓이고, 그 시간이 압축되면 직관이 된다고 본다.

규칙 한 줄의 표현도 여러 번 시도해 본 뒤 실제로 Agent가 따르는 표현을 남겼고, Hooks를 써야 할 순간과 Skill의 적절한 크기도 실패를 여러 번 겪은 뒤 알게 되었다고 서술한다.

직관은 설명할 수 없어서 비과학적인 것이 아니다. 아직 언어로 완전히 분해하지 못한 반복 경험의 압축물일 수 있다. Harness를 잘 다루는 감각도 같은 방식으로 자란다는 것이 이 장의 자기분석이다.

경험은 건너뛸 수 없다 — 다만 경기장이 바뀐다

원문은 Martin Fowler가 제기한 “처음부터 사람이 loop 밖에 있다면 다음 세대 Harness 설계자는 어떻게 자라는가”라는 우려를 다시 다룬다. 코드 작성 경험이 줄어드는 것이 위험할 수 있다는 문제의식에는 동의하지만, 필요한 경험이 반드시 전통적인 코딩 경험과 같은 형태일 필요는 없다고 주장한다.

전통적인 Junior Developer의 경험

시간을 들여 프로그래밍 언어와 시스템을 직접 다루며 판단력을 쌓는다.

문법
자료구조
디버깅
성능·메모리 문제
코드베이스 유지보수

AI 협업에서 쌓이는 다른 경험

비슷한 시간 동안 Agent의 성향과 작업 흐름을 반복해서 다루며 판단력을 쌓는다.

환각과 게으름의 패턴
Prompt 표현의 민감도
규칙과 Hook의 경계
Skill의 적절한 입도
컨텍스트·라우팅 설계

원문의 요지는 경험을 없애는 지름길이 생겼다는 것이 아니다. 같은 시간을 다른 대상에 투자할 수 있게 되었다는 것이다. 트랙은 달라져도 충분한 반복과 실패가 필요하다는 조건은 남는다.

“코딩 경험을 대체할 수 있는가”라는 질문보다 더 근본적인 질문이 있다. 어떤 종류이든 충분한 경험을 축적하지 않고 복잡한 Harness를 설계할 수 있는가. 이 장의 답은 부정적이다. 지름길은 없고 경로만 달라졌다.

현재의 구조 — 8KB 미만의 입구, 100+ Skills, 장기 기억

원문은 현재 Harness의 대략적인 구조를 공개한다. 한 파일에 모든 것을 집어넣는 대신, 라우터·하위 규칙·공유 규칙·Skills·Memory가 서로 다른 역할을 담당한다.

<8KB Root CLAUDE.md 정체성·스타일·프로젝트 구조를 알고 필요한 하위 규칙으로 라우팅.

① 하위 CLAUDE.md

작업공간별로 완전한 흐름을 분리한다. 글쓰기는 주제→조사→작성→교정→이미지→게시, 영상은 자막→분석→스크립트→교정, iOS 개발은 자체 아키텍처 규칙을 가진다.

② 공유 규칙 파일

여러 작업공간에서 재사용하는 AI 느낌 제거용 교정 규칙, 이미지 처리 흐름, 정보 검색 규범 등을 별도 참조 디렉터리에 둔다.

③ 100+ Skills

조사, 작성, 이미지, 교정, Feishu 동기화, 영상 분석, PDF 생성까지 전 과정을 능력 패키지로 분리한다. 필요할 때만 로드하므로 평소에는 컨텍스트를 차지하지 않는다.

④ Memory System

정체성, 현재 프로젝트, deadline, 모델 버전 메모 같은 장기 정보를 유지한다. 새 대화마다 핵심 기억을 자동으로 불러와 같은 설명을 반복하지 않게 한다.

이 구조는 하루에 설계한 것이 아니라 빈 파일에서 시작해 약 8개월 동안 조금씩 성장했다고 원문은 설명한다.

작은 입구가 큰 시스템을 통제한다. Root 파일은 모든 지식을 담는 창고가 아니라 필요한 지식으로 연결하는 인덱스다. 이 구조의 목적은 정보의 총량을 키우는 것이 아니라 필요한 순간의 신호 밀도를 높이는 데 있다.

제로 베이스에게 주는 결론 — 먼저 빈 파일을 연다

마지막 조언은 복잡한 프레임워크가 아니다. 코딩 경험이 없거나 적다면 오히려 아무것도 쓰지 않은 지시 파일에서 시작하라고 한다. 그리고 실제로 거슬리는 첫 번째 실패를 기다린다.

빈 파일을 만든다

처음부터 이상적인 규칙 세트를 상상해 채우지 않는다.

첫 번째 실패를 기다린다

실제로 반복을 막을 가치가 있는 문제인지 확인한다.

한 줄을 추가한다

두 번째 실패가 오면 다시 한 줄을 추가한다.

몇 달 뒤 다시 본다

그 파일에는 자신의 상황·불편·업무 방식이 압축되어 있다.

원문은 필요한 것을 프로그래밍 경험보다 인내와 시간이라고 표현한다. AI의 서툼을 견디는 인내, 반복 속에서 “언제 무엇을 믿고 무엇을 강제해야 하는가”라는 감각을 축적하는 시간이다.

좋은 Harness는 책상 위에서 완성되는 설계도가 아니다. AI와 여러 번 부딪히며 생긴 흔적이 규칙이 되고, 규칙이 구조가 되고, 구조가 다시 새로운 경험을 받아들이며 자란다.

빈 파일에는 아무것도 없지만
그래서 무엇이 필요한지 아직 결정되어 있지 않다.

첫 번째 불편이 한 줄이 되고,
한 줄들이 서로 부딪히면 길이 갈라지고,
말로 부족한 곳에는 울타리가 생기고,
반복되는 일은 하나의 능력으로 묶인다.

시스템은 처음부터 큰 것이 아니었다.
관계가 오래되면서 구조가 생긴 것이다.

경험은 건너뛸 수 없다.
다만 무엇과 부딪히며 경험할 것인가는 달라질 수 있다.

이 웹페이지는 첨부 문서 《Harness Engineering》의 §12 「花叔：零代码经验到百万用户 / Huashu: From Zero Coding to a Million Users」 (PDF 55–60쪽)에만 근거해 재구성했다. 61쪽에서 §13이 시작되는 것을 확인해 12장의 범위를 분리했다. 원문의 제로 코딩 사례, 빈 CLAUDE.md에서의 규칙 축적, Router 리팩터링, 규칙과 Hooks의 구분, 100개가 넘는 Skills, 성장 루프, 반복 경험과 직관에 대한 자기분석, 경험의 불가피성, 현재의 8KB 미만 Root CLAUDE.md·하위 규칙·공유 규칙·Skills·Memory 구조, 그리고 제로 베이스 독자에게 주는 마지막 조언을 보존했으며 외부 자료를 이용한 검증·정정·확장은 수행하지 않았다.