테크 라이팅 문서 시스템에 하네스를 도입하다
이 글은 그 자체로 한 번의 실험이다. 초안이 하네스 v1.0에서 잉태됐고, 본문을 채우는 동안 정원은 v1.2.0까지 자랐다.
1. 하네스 도입 배경
테크 라이팅 팀은 2026년 5월부터 하네스 도입을 시작했다. 이유는 두 가지다 — 흐름이 그쪽으로 가고 있다는 외부 신호, 그리고 우리가 풀지 못하던 문제가 마침 그 모양으로 생겼다는 내부 신호.
1.1 외부 신호 — 프롬프트에서 컨텍스트로, 컨텍스트에서 하네스로
AI 엔지니어링의 무게중심은 빠르게 옮겨가고 있다. 2022-2023년의 화두는 프롬프트 엔지니어링이었다. "어떻게 묻느냐"가 결과를 좌우했다. 2024-2025년은 컨텍스트 엔지니어링의 시대였다. 모델이 더 똑똑해지자 병목이 "표현"에서 "정보"로 옮겨갔고, 엔지니어는 컨텍스트 윈도우에 무엇을 넣을지 큐레이션하는 사람이 되었다.
2026년 들어 다음 단계의 윤곽이 잡혔다 — 하네스 엔지니어링. 프롬프트가 명령을 빚고, 컨텍스트가 시야를 빚는다면, 하네스는 에이전트가 살아갈 환경 전체를 빚는다. 도구·메모리·가드레일·관측성·피드백 루프까지 한 묶음으로 본다.
"AI는 강력한 말이다. 마구(harness)를 씌워야 올바른 방향으로 달린다." — Blumn.AI 블로그, 하네스 AI 엔지니어링
이 흐름은 한 회사의 마케팅 멘트가 아니다. 2026년 상반기에만 Faros, Atlan, Medium, Data Science Dojo, Epsilla 같은 곳에서 "프롬프트→컨텍스트→하네스"의 3단계 진화를 정리한 글들이 잇따라 나왔다. 공통된 진단은 이렇다 — 모델은 충분히 똑똑해졌고, 부족한 것은 모델이 실수 없이 반복 작업을 수행할 환경이다.
1.2 내부 신호 — 우리 팀이 그 환경을 가장 먼저 필요로 했다
테크 라이팅이라는 영역은 작지만 하네스의 모든 요건을 압축해서 보여준다.
- 반복: 비슷한 구조의 문서가 끊임없이 생산된다
- 품질의 일관성: 한 사람이 쓴 것처럼 들려야 한다
- 검수가 사람의 시간을 가장 많이 잡아먹는 단계: 작성보다 점검이 길다
- 외부 게시 압력: 발행되면 되돌리기 어렵다
그래서 우리는 작은 영역을 골랐다. 거대한 제품 매뉴얼이나 비즈니스 백서 대신, 테크 라이팅 — 공개 가능한 기술 글을 하나씩 발행하는 작업 — 을 첫 실험실로 삼았다. 이 영역에서 자란 하네스가 더 큰 영역(제품 매뉴얼, 사내 위키, 학습 자료)으로 옮겨갈 때 무엇을 가져가고 무엇을 버릴지 데이터가 쌓일 것이다.
2. 우리가 가진 문서화의 문제
원고나 지침 없이 최종 출판물만 관리할 때 어떤 일이 벌어지는가. 우리 팀이 직접 겪었거나 가까운 곳에서 본 패턴들이다.
2.1 포맷 파편화
PDF, 워드, 구글 독스, Notion, Confluence, 사내 위키… 같은 문서가 여러 포맷으로 흩어진다. "최신본이 어느 거예요?"라는 질문이 매번 떠오른다. 누군가 PDF를 받아 워드로 편집하고 다시 PDF로 내보내면 그 사이의 모든 변경이 사라진다.
2.2 버전 관리 부재
문서에는 일반적으로 diff가 없다. 코드처럼 "지난 주 대비 무엇이 바뀌었나"를 한눈에 볼 수 없으면, 검수자는 매번 처음부터 다시 읽어야 한다. 검수 비용이 글의 크기에 정비례한다.
2.3 일관성 유지의 어려움
같은 개념을 어떤 글에서는 "캐시", 다른 글에서는 "캐쉬", 또 다른 글에서는 "cache"로 부른다. 어떤 글은 "~합니다", 어떤 글은 "~한다". 독자는 무의식적으로 이 불일치를 감지하고 신뢰를 깎는다. 그러나 작성자 입장에서 매번 모든 글의 표기를 동시에 보는 것은 불가능하다.
2.4 품질 평가 기준의 부재
"좋은 문서"의 기준이 사람마다 다르다. 어떤 검수자는 명확성을 보고, 어떤 검수자는 톤을 보고, 어떤 검수자는 사실 정확성을 본다. 같은 글을 두 사람이 검수하면 두 가지 답이 나온다. 작성자는 어느 피드백을 따라야 할지 알 수 없다.
2.5 협업 충돌
여러 사람이 같은 문서를 동시에 편집하면 머지 충돌이 발생한다. 워드/구글 독스의 실시간 편집 기능도 글의 구조 변경까지 책임지지는 못한다. "당신이 추가한 단락을 내가 옮겨버렸는데 괜찮을까요"의 협상이 매번 일어난다.
2.6 유지보수의 누적 비용
기능이 업데이트되면 관련된 모든 문서를 찾아 수정해야 한다. 검색이 잘 안 되는 포맷일수록 누락이 늘어난다. 어느 시점부터는 "낡은 문서를 잡아내는 사람"이 풀타임으로 필요해진다.
2.7 사이클을 무너뜨리는 결정적 변수 — 담당자 교체
위의 1번부터 6번까지가 천천히 누적되는 문제라면, 7번은 갑자기 모든 것을 뒤집는다. 담당자가 바뀌면 문서의 종류 자체가 바뀐다. 새 담당자는 자신이 익숙한 도구와 양식으로 다시 시작한다. 이 사이클을 우리는 여러 번 봤다.
이 모든 문제는 최종 출판물에 모든 진실을 담아두려고 했기 때문에 생긴다. 출판물은 산출물이지 작업물이 아니다. 출판물부터 관리하면 검수가 없고, 검수가 없으면 일관성이 없다.
3. 오픈소스와 출판사로부터 찾은 방법
문제 정의가 끝나자 답은 가까이 있었다. 둘 다 — 출판사와 오픈소스 — 이미 오래 전부터 같은 방식으로 풀고 있었다.
3.1 출판사가 책을 만드는 법
출판사는 완성된 책을 관리하지 않는다. 원고(manuscript) 를 관리한다. 학술 출판의 표준 워크플로우만 봐도 그렇다. 저자가 제출하면 편집실이 형식·범위 적합성을 1차 점검한다(initial screening). 편집장은 본문 품질과 신규성을 2차로 본 뒤 외부 동료 평가자에게 회람한다. 평가자의 수정 요청이 돌아오고, 그것을 반영한 수정본이 통과하면 그제야 제작(production) 단계로 넘어간다 — 조판·교정·인용 검증을 거쳐 인쇄에 이른다. 인쇄소는 원고 흐름의 끝점이지 시작점이 아니다.
핵심은 status 워크플로우다. submitted → under review → revision → accepted → in production → published. 각 status마다 무엇을 점검할지, 누가 점검할지가 정해져 있다.
3.2 오픈소스가 문서를 관리하는 법 — Docs as Code
오픈소스 진영의 답은 docs-as-code다. 문서를 코드와 같은 저장소에 두고, 같은 도구(Git, Pull Request, Continuous Integration, 정적 사이트 생성기)로 다룬다. 마크다운 같은 plain text로 작성하면 diff가 보이고, Pull Request(PR)로 리뷰가 되고, Continuous Integration(CI, 통합 빌드 자동화)으로 검증이 되고, 머지되면 사이트가 빌드된다.
도구는 충분히 성숙했다. 2026년 기준으로 Docusaurus는 GitHub 별이 6.4만 개를 넘고, MkDocs는 9만 개 이상의 GitHub 프로젝트의 문서를 떠받친다. 두 도구의 정적 사이트 빌드 패턴은 거의 표준이 되었다. (Docusaurus vs MkDocs 비교, Docsio)
실제 사례 — 큰 프로젝트들은 어떻게 굴리는가
추상적인 원칙을 넘어, 실제로 이 방식을 운영하는 오픈소스/회사들의 사례를 보면 패턴이 더 분명해진다.
Kubernetes — 원고가 곧 단일 출처
거대 클라우드 네이티브 프로젝트인 Kubernetes는 모든 문서를 kubernetes/website 저장소 한 곳에 모아 둔다. Hugo(Go로 짠 정적 사이트 생성기) + Docsy(Hugo용 기술 문서 테마)로 사이트를 빌드하고, 다국어와 버전을 모두 같은 저장소에서 관리한다. 새 글이나 수정은 일반 코드 기여처럼 GitHub Pull Request로 들어오고, SIG-Docs(문서 특별 관심 그룹) 가 리뷰한다. 문서 빌드가 깨지면 PR이 머지되지 않는다 — CI가 검수의 1차 게이트다. (Kubernetes Website Repo)
GitHub Docs — 문서 자체가 오픈소스
GitHub의 공식 문서 docs.github.com 는 그 자체가 공개 저장소(github/docs) 다. 사내·사외 누구나 PR을 보낼 수 있고, GitHub 직원이 리뷰한다. 한 검색 결과의 표현을 빌리면 "anyone from inside or outside the company can contribute". 문서가 코드 옆에 있으니 기능이 바뀌면 같은 PR에서 문서도 바뀐다.
Stripe — 90+ 공개 저장소, 모든 PR이 내부 워크플로우를 발동
API(Application Programming Interface) 문서로 유명한 Stripe는 90개에 가까운 공개 저장소와 9개의 공식 클라이언트 라이브러리(SDK, Software Development Kit)를 운영한다. 흥미로운 점은 "every pull request to an SDK or API library kicks off an internal workflow to review and accept the contribution" — 외부 PR이 들어올 때마다 내부 검수 파이프라인이 자동으로 가동된다. 외부 기여를 받지만 품질 게이트는 사내가 잡는 구조다. (How Stripe uses GitHub)
Squarespace 엔지니어링 — 사내 문서를 docs-as-code로 옮긴 회고
사내 도입 사례도 있다. Squarespace 엔지니어링 블로그의 "Making Documentation Simpler and Practical: Our Docs-as-Code Journey" 는 사내 문서를 Confluence에서 Git 저장소로 옮긴 경험을 정리한다. 코드 리뷰 체크리스트에 "이 변경이 문서를 바꿔야 하는가"가 들어가면서, 코드와 문서가 같은 PR로 묶이는 것이 가장 큰 효과였다고 보고한다. (Squarespace Engineering Blog)
이 사례들에서 반복되는 패턴은 셋이다:
- 한 곳에 모인 원고 — 단일 저장소, 단일 디렉터리, 단일 포맷(주로 마크다운)
- PR이 검수의 진입점 — diff와 코멘트가 검수의 인터페이스
- CI가 1차 게이트 — 빌드 실패 = 머지 차단
우리 정원의 manuscript/articles/, manuscript-architect의 lint, GitHub Actions의 deploy-docusaurus.yml 이 정확히 이 세 줄에 대응한다. 우리는 거인의 어깨에서 시작한 셈이다.
3.3 그래서 — AI 시대에도 원고가 먼저다
여기서 한 가지 함정에 빠지기 쉽다. "AI가 충분히 똑똑하니 출판물을 던지면 알아서 품질 관리 해주지 않나?" 단기적으로는 가능하다. 프롬프트 엔지니어링으로 오탈자나 톤 일부는 빠르게 잡을 수 있다.
문제는 지속이다. 한 번의 LLM(Large Language Model) 호출로 잡은 품질은 다음 글에서 자동으로 유지되지 않는다. 같은 글에서 잡힌 톤 위반이 옆 글에서는 그대로 통과한다. 우리는 매번 처음부터 다시 묻게 된다. 품질 관리의 라이프사이클이 없기 때문이다.
원고 관리는 그 자체가 라이프사이클이다. 원고가 한 곳에 모여 있고, status가 있고, 검수 기준이 분리되어 있으면, 같은 점검을 다음 글에도 적용할 수 있다. 점검은 누적된다.
출판물의 품질을 당장 바꿔야 한다면 프롬프트 엔지니어링이 맞다. 출판물의 품질을 지속해서 관리하고 싶다면 하네스가 맞다.
이 차이가 우리 팀이 하네스를 도입한 진짜 이유다.
4. 이 프로젝트가 초기에 도입한 장치들
하네스를 도입했다고 해서 글의 퀄리티가 다음 날 갑자기 올라가지 않는다. 하네스가 보장하는 것은 다른 것이다 — 사이클 자체의 지속적 개선. 이번 절은 그 사이클을 실제로 굴리기 위해 우리가 심은 장치들을 분해한다.
4.1 정원이라는 은유 — 3-Layer 토양
우리가 채택한 하네스의 이름은 블룸AI 하네스의 정원 (BlumnAI Harness Garden) 이다. 오픈 스타터팩으로 배포되며 — 그 배포 이름은 카카시(kakashi) 다 — 누구나 가져다 자기 정원을 만들 수 있다. 핵심 은유는 이름 그대로 정원이다.
| 층 | 디렉터리 | 비유 | 역할 |
|---|---|---|---|
| Layer 1 | harness/knowledge/ | 햇빛 | 도메인 지식 — 무엇이 올바른지 판단하는 기준 |
| Layer 2 | harness/agents/ | 영양분 | 전문 검수자 — 실제 검수를 수행하는 주체 |
| Layer 3 | harness/engine/ | 물길 | 워크플로우 — 검수가 흐르는 순서와 범위 |
햇빛 없이는 꽃이 방향을 잃고, 영양분 없이는 꽃이 피지 않고, 물길 없이는 꽃이 말라간다. 세 층이 모두 갖춰져야 하나의 검수 사이클이 굴러간다.
이 은유는 단순한 수사가 아니다. 하네스 엔지니어링의 표준적 정의 — "도구 오케스트레이션 + 검증 루프 + 컨텍스트/메모리 + 가드레일 + 관측성"의 5개 레이어 — 와 거의 그대로 대응한다. 우리는 그것을 도메인에 맞게 단순화한 형태로 적용한 셈이다.
4.2 지금 정원에 살고 있는 전문가 6명
원고 한 편이 게시되기까지 우리 정원에는 여섯 명의 전문가가 손을 거든다.
사용자 요청
│
▼
┌──────────────────────────────────────────────────┐
│ tamer (정원지기) │
│ · 메타 에이전트 — 정원 자체를 돌본다 │
│ · 새 꽃 심기, 토양 점검, 평가 로그 관리 │
└────────────────┬─────────────────────────────────┘
│ 위임
┌─────────────┼─────────────┐
▼ ▼ ▼
┌─────────┐ ┌─────────┐ ┌─────────────┐
│manuscript│ │full- │ │docs- │
│-architect│ │review │ │publisher │
│편집장 │ │검수단 │ │출판 전문가 │
│(원고지) │ │(내용) │ │(빌드/배포) │
└─────────┘ └────┬────┘ └─────────────┘
│
┌─────────┼──────────┐
▼ ▼ ▼
┌────────┐ ┌────────┐ ┌────────────┐
│doc- │ │style- │ │terminology-│
│reviewer│ │enforcer│ │keeper │
└────────┘ └────────┘ └────────────┘
명확성/구조 문체/표기 용어/약어
각 전문가는 자신의 영역만 본다. 충돌과 누락을 막기 위해 위임 규칙이 명시되어 있다.
| 전문가 | 보는 것 | 영역 외 처리 |
|---|---|---|
| tamer (정원지기) | 정원 자체 — 구조, 평가 로그 트렌드 | 도메인 작업은 다른 전문가에게 위임 |
| doc-reviewer (문서 검토관) | 명확성, 구조, 독자 친화성 | 문법은 style-enforcer에게 |
| style-enforcer (스타일 수호자) | 문체 일관성, 표기 규칙, 톤 | 용어 정의는 terminology-keeper에게 |
| terminology-keeper (용어 사서) | 용어 일관성, 정의, 약어 | 표기 스타일은 style-enforcer에게 |
| manuscript-architect (편집장) | frontmatter, 자리표시자, status 워크플로우 | 본문 명료성은 doc-reviewer에게 |
| docs-publisher (출판 전문가) | 빌드, 배포, 깨진 링크 진단 | 원고 자체는 손대지 않음 |
4.3 햇빛 — 5권의 지식 문서
각 전문가는 자신만의 판단 기준(knowledge/)을 갖는다.
| 지식 문서 | 누가 본다 | 무엇이 들어있나 |
|---|---|---|
doc-clarity-principles.md | doc-reviewer | 헤딩 위계, 문단 길이, BLUF, 전제 친절도 등급 |
writing-style-guide.md | style-enforcer | 한국어 문서의 어조 선택, 영문 단어 표기, 숫자·단위 규칙 |
technical-terminology.md | terminology-keeper | 자주 흔들리는 용어의 권장 표기, 약어 풀어쓰기 표준 |
manuscript-conventions.md | manuscript-architect | frontmatter 스키마, 자리표시자 TYPE, status 승급 조건 |
docs-publishing.md | docs-publisher | Docusaurus 설정·트러블슈팅, GitHub Pages 권한 |
지식 문서가 분리되어 있어야 — 점검 기준이 갱신될 때 한 곳만 고치면 모든 글에 자동으로 적용된다. 그것이 라이프사이클의 핵심이다.
4.4 물길 — 2개의 엔진(워크플로우)
전문가가 모인다고 검수가 되지는 않는다. 누가 먼저 보고, 누가 나중에 보고, 어디서 멈추는지가 정해져야 한다. 그 흐름이 engine/이다.
full-review — 내용 검수 풀 리뷰
한 편의 원고에 대해 세 명의 검수자가 동시에 자기 영역을 본 다음, 통합 리포트로 묶는다.
원고 한 편
│
├─→ doc-reviewer : 명확성/구조/독자 친화성
├─→ style-enforcer : 문체/표기/톤
└─→ terminology-keeper : 용어/약어/정의
│
▼
통합 리포트
(우선순위 Top 5 + 영역별 점수)
publication-pipeline — 골격부터 배포까지
엔진은 단지 검수만 아니다. 한 편의 글이 골격에서 GitHub Pages에 도달하기까지의 전 흐름을 정의한다.
Stage 1: 골격 생성 (manuscript-architect)
└─ _template.md → frontmatter 채움, 자리표시자만 남김 (status: draft)
Stage 2: 본문 작성 (사람)
└─ 자리표시자를 실제 문장으로 교체 (status: review로 수동 승급)
Stage 3: 내용 검수 (full-review 호출)
└─ 3인 검수단 통합 리포트
Stage 4: 형식 lint + 승급 (manuscript-architect)
└─ 자리표시자 잔존 0건, 점수 ≥ B 또는 ≥ 3 확인 → status: published
Stage 5: 빌드 + 배포 (docs-publisher / CI)
└─ Docusaurus 빌드 → GitHub Pages
Stage 3가 full-review를 호출하는 부분이 중요하다. 같은 엔진이 두 군데에서 재사용된다 — publication-pipeline의 Stage 3에서 자동으로, 그리고 사용자가 직접 전체 점검해를 호출할 때 단독으로. "검수"가 작은 단위로 분리되어 있어 다른 흐름에서도 끼워 쓸 수 있다.
4.5 영양분 외 — 순수 도구는 스킬로 분리
판단(전문가)과 생산(도구)은 분리되어 있다. 같이 묶으면 둘 다 무거워진다.
이미지 생성은 좋은 예다. "이 글에 어떤 이미지가 필요한가"는 편집장의 판단이지만, "그 이미지를 어떻게 만드는가"는 단순 호출이다. 그래서 우리는 OpenAI의 gpt-image-2 호출을 하네스 외부의 순수 스킬(.claude/skills/image-gen/)로 분리했다.
- 시크릿(API 키)은
.secret/openai.json에서 읽고, 같은 디렉터리의*.json은.gitignore로 차단 - 생성된 이미지마다 프롬프트와 모델 메타가
.prompts/<slug>.md에 자동 보존되어 재현/변형이 쉽다 - 향후 편집장 워크플로우가 이 스크립트를 직접 호출하는 단계를 포함할 수 있다
이런 분리가 중요한 이유: 도구가 바뀌어도 판단은 그대로다. gpt-image-2에서 다른 모델로 옮겨가더라도 편집장의 "이 자리에 일러스트가 필요하다"는 판단은 유효하다.
4.6 단일 출처와 출판 도구의 분리
원고는 manuscript/articles/에 있고, 정적 사이트 빌드 도구는 docs-docusaurus/에 있다. 빌드 도구는 원고를 읽기만 한다. 사람이 손대는 곳은 단 한 곳이다.
manuscript/articles/*.md ← 단일 출처 (사람이 쓴다)
│
│ scripts/copy-from-manuscript.mjs
│ (frontmatter status 필터)
▼
docs-docusaurus/docs/ ← 자동 생성 (gitignored)
│
│ npm run build
▼
docs-docusaurus/build/ ← 빌드 산출물 (gitignored)
│
│ GitHub Actions deploy
▼
https://blumnai-studio.github.io/tech-writing-harness/
copy-from-manuscript.mjs는 frontmatter status: published인 글만 통과시킨다. CI 환경변수 한 줄(MANUSCRIPT_STATUS_FILTER)로 필터를 바꿀 수 있어, 로컬에서는 draft까지 미리 볼 수 있다.
4.7 평가 — 정원지기의 3축
마지막 장치 하나. 모든 작업은 끝나면 평가된다. 정원지기(tamer)가 매기는 점수는 세 축이다.
| 축 | 평가 대상 | 척도 |
|---|---|---|
| 워크플로우 개선도 | 효율성 향상 여부 | A/B/C/D |
| Claude 스킬 활용도 | 프로젝트 스킬 연동 | 1~5점 |
| 하네스 성숙도 | 3-Layer 충실도 | L1~L5 |
평가는 단순한 점수표가 아니다. 점수가 누적되면 어느 영역이 약점인지가 드러난다. 약점이 드러나면 다음 사이클에서 무엇을 보강할지가 자동으로 결정된다.
5. 마치며 — 글을 쓸수록 자라는 정원
이 글의 초안은 블룸AI 하네스의 정원 v1.0에서 잉태됐다. 빈 정원에 정원지기 한 명만 있던 상태. 본문을 채우는 동안 정원은 v1.1.0(검수 3인 영입), v1.2.0(편집장과 출판 전문가 영입)로 자랐다.
다시 말해 — 이 글이 작성되는 과정 자체가 하네스를 자라게 한 라이프사이클의 한 사이클이다. 검수가 일어날 때마다 누락된 규약이 드러나고, 그 규약이 지식 문서로 빠지면 다음 글에서는 그 점검이 자동으로 일어난다.
이 패턴이 유효하다는 가설을 우리는 작은 영역에서 먼저 시험하고 있다. 테크 라이팅이라는 정원에서 충분히 굴러간 뒤에는, 같은 패턴을 더 큰 영역으로 옮겨갈 것이다.
처음에는 정원이 글을 다듬는다. 시간이 지나면 글이 정원을 다듬는다. 그 사이의 어딘가에서 라이프사이클이라 부를 만한 것이 시작된다.
참고
- 하네스 엔지니어링 개념:
- 출판 워크플로우:
- Docs-as-code 도구와 사례:
- Docusaurus 공식 사이트
- Docusaurus vs MkDocs (Docsio, 2026)
- Kubernetes Website Repository — SIG-Docs 가 운영하는 단일 출처 저장소
- GitHub Docs 공개 저장소 — 공식 문서가 오픈소스로 운영되는 사례
- How Stripe uses GitHub (Customer Story) — 90+ 공개 저장소, 외부 PR이 사내 워크플로우를 자동 발동
- Squarespace Engineering — Our Docs-as-Code Journey — 사내 도입 회고
- 이 프로젝트가 시작한 블룸AI 하네스의 정원팩 (배포 이름: 카카시):