하네스 엔지니어링으로 서비스 만들어보기

[준비물]

• Claude Code : 아이디에이션 & 문서 협의
• Codex : 코드 중심 작업에 활용
• Git : 버전 관리 & 롤백 안전망
• Language : 본인이 쓰는 개발 언어

직접 만드는 것’이 아니라, AI가 일하기 좋은 환경(하네스)을 설계해서 결과물을 함께 만들어가는 방법을 정리. 핵심 : 문서 → 점검 → 실행 루프 → 갱신의 반복

1) 하네스 구조 작성

처음에는 “어떤 문서를 어떤 폴더에 둘지” 같은 뼈대부터 합의하는 게 좋다.

[예시]

안녕 나는 OO 앱을 만들고 싶어. 
근데 그 앱을 내가 직접 만드는게 아니라 하네스 엔지니어링을 통해 만들고 싶어. 
아래와 같은 구조를 짜봤는데 내용을 어떤걸 넣어가면 좋을지 하나하나 의논해볼까?

AGENTS.md
ARCHITECTURE.md
docs/
├── design-docs/
│   ├── index.md
│   ├── core-beliefs.md
│   └── ...
├── exec-plans/
│   ├── active/
│   ├── completed/
│   └── tech-debt-tracker.md
├── generated/
│   └── db-schema.md
├── product-specs/
│   ├── index.md
│   ├── new-user-onboarding.md
│   └── ...
├── references/
│   ├── design-system-reference-llms.txt
│   ├── nixpacks-llms.txt
│   ├── uv-llms.txt
│   └── ...
├── DESIGN.md
├── FRONTEND.md
├── PLANS.md
├── PRODUCT_SENSE.md
├── QUALITY_SCORE.md
├── RELIABILITY.md
└── SECURITY.md

이 예제에서는 초기 아이디에이션에 Claude를 사용한다. 선택지를 받아 비교하되, 최종 범위와 완료 조건은 사람이 문서로 확정한다.

---

2) 문서가 쌓여 완성 후, 일관성 점검 수행

문서를 어느 정도 작성했다면, 다음 프롬프트로 모순/누락/용어 불일치를 빠르게 잡아낸다.

여태까지 쓴 문서 다 검토해서, 논리적으로 일관적인지, 모순이 없는지 재검토해줘

---

3) 문서 파일을 기반으로 Claude Code 실행

이 단계부터는 “AI가 코드를 쓰기 위해 필요한 맥락”을 문서로 제공하는 방식으로 협업

안녕 나는 이 폴더에서 repository level harness engineering과 application level harness engineering을 구현하고 싶어.
여기서 내가 xxx 폴더 안에 있고, 이 파일들은 내가 여태까지 application을 생각하면서 만든 작업물이야.
이 작업물을 모두 읽은 후 repository harness engineering을 구현하는 이야기를 같이 해봤으면 해

---

4) 흔들리지 않는 ‘헌법(Constitution)’을 같이 만들기

AI에게 통째로 맡기지 말고, 내 기준을 AI와 공동 작성해야 한다. 헌법이 흔들리면 문서/코드/테스트가 함께 흔들립수 있다.

[시작방법]

나는 유튜브 교육용으로 앱을 만들려고 해. 간결해야하고, 쉬워야 하고, 안전해야 해

# Constitution

## 1. Purpose
이 저장소는 교육용 앱을 설계, 구현, 검증 한다.
초보자가 읽고 따라갈 수 있어야 한다.

## 2. Core Values
- 간결정: 복잡하면 쪼개고 제거한다.
- 검증 가능성 : 문서, 코드, 테스트 일치
- 안전성: 사용자 데이터 = 보호 대상

## 3. Non-Negotiables
- 문서 없이 기능을 추가하지 않는다.
- 테스트를 속여서 통과시키지 않는다.

---

5) AI가 다양한 관점으로 문서를 ‘평가’하게 하기

문서를 평가하게 하면, 개선 포인트가 구조적으로 드러난다.

네가 시니어 개발자라면, 이 문서를 어떻게 평가할 것 같아?
문서를 평가하는 n개의 기준을 제시하고 점수로 평가해줘

추가 기준 예시:

• 문서 500줄 이하
• 한 문서에 한 책임
• 용어 일관성 점검

소프트웨어 엔지니어 — 코드 구조/확장성 관점에서 문제 찾기

• 코드 구조와 확장성 관점에서 문제를 찾아줘

보안 담당자 — 보안 취약점/위험 요소 찾기

• 어떤 보안 취약점이나 위험을 발견할 것 같아?

초보 개발자 — 따라 할 수 있는지(학습 난이도) 점검

• 이 문서를 읽고 나도 따라할 수 있을 것 같아?

---

6) 모호한 표현 없애기: 기준을 숫자로 고정하기

BEFORE — 모호한 표현(X)

한 두번의 수정 후에도 같은 문제가 남아 있을 때 이 흐름을 사용한다

AFTER — 명확한 기준(O)

5회 수정 시도한 후에도 같은 문제가 남아 있을 때.
AI가 최대한 자율성을 발휘해서 고민하고 수정하다가 안되면 기록한다.

마지막 점검 요청

운영을 잘 수행하기 위해, 규칙은 강건한지, 모호한 것은 없는지,
업무가 잘 쪼개졌는지, 인수인계 조건은 갖춰졌는지 다시 점검해줘.

---

7) Git을 연결해 ‘안전망’을 만들기

파일 백업 방식

파일 복사본 기반 국소 복구
- 내가 손댄 파일 하나는 되돌릴 수 있다
- 여러 파일에 걸친 작업은 복구 불가

Git 기반 롤백

저장소 전체 상태 기반의 복구
- 여러 파일에 걸친 작업을 한 번에 복구
- AI가 자율적으로 일할수록 필수

---

8) 암묵지 좁히기: “내 머릿속 기준”을 문서로 바꾸기

암묵지란? 내 머릿속에는 있는데 , AI한테 아직 전달 안된 것들. “당연히 이렇게 하겠지” 하고 내가 가정하는 것들. 즉, 내 머릿속에는 있지만 AI에겐 전달되지 않은 가정

내 생각

교육용이니까 당연히 코드가 짧고 읽기 쉬워야지

AI 행동(문서에 없으면 이렇게 될 수 있음)

문서에 명시 안되어 있으니 그냥 잘 돌아가는 코드를 써요
300줄 짜리 함수라도요

방법: 쓰면서 발견 → 바로 문서화 → 반복 (이 과정이 곧 하네스 고도화)

---

9) 실행 루프를 돌리고, 결과물로 검증하기

마지막 단계에서는 테스트/코드/문서가 같이 움직여야 한다.

[마지막 단계 실행루프 돌리기(Gradio 웹 활용)]

app.py의 Gradio UI 구조를 리뷰해서 레이아웃이 깨지는지 확인하고 실행 후 브라우저 기준으로 수정해줘. 수정 후에는 회귀 테스트도 추가하고, harness 문서와 tracker도 현재 상태에 맞게 갱신해줘

실행 루프 사이클

• 테스트 돌리기 → 코드 수정 → 사이트 빌드 → 문서 갱신 → 결과 확인
• 결과 확인 → 피드백 → 재검증 → 수정 — 만족할 때까지 이 사이클을 반복

---

작은 서비스 예제: 교육용 FAQ 화면

위 절차를 한 기능에 적용해 보자. 교육 과정 FAQ를 검색해 답을 보여주는 Gradio 화면을 만든다고 가정한다. 처음부터 LLM을 붙이면 검색 실패와 생성 실패를 구분하기 어렵다. 먼저 두 개의 고정된 질문으로 작동하는 기본선을 만들고, 그다음 승인된 문서 검색과 모델 생성으로 교체한다. 이 예제는 설계·코드 예시이며 실행 결과를 주장하지 않는다.

[기능 계약]

입력	기대 동작	검증
“수업 시간”	저장된 시간 안내와 출처 ID	답과 출처가 함께 있는지
“과제 제출”	마감 안내와 출처 ID	해당 FAQ만 사용했는지
자료 없는 질문	근거 부족 안내	추측한 날짜·금액이 없는지
공백 또는 300자 초과	입력 오류	모델·검색 호출 전 거절

flowchart LR
    U[Gradio 입력] --> V[길이·공백 검증]
    V --> L[허용 FAQ 조회]
    L -->|없음| N[근거 부족 안내]
    L -->|있음| F[답 + 출처 ID]
    N --> UI[화면 출력]
    F --> UI
    V -->|실패| E[입력 오류]

이 단계의 lookup은 모델을 호출하지 않는다. 그래서 화면, 입력 검증, 출처 표시라는 서비스 경계를 먼저 확인할 수 있다. LLM을 추가할 때는 lookup의 반환 자료만 모델에 전달하고, 모델이 만든 출처 ID가 조회 결과에 있는지 다시 검사한다.

[faq.py]의 핵심 함수는 다음처럼 작게 만든다.

FAQ = {
    "수업 시간": ("월·수 19:00", "FAQ-01"),
    "과제 제출": ("매주 일요일 23:59", "FAQ-02"),
}

def answer_faq(question: str) -> str:
    cleaned = question.strip()
    if not cleaned or len(cleaned) > 300:
        raise ValueError("질문은 1자 이상 300자 이하로 입력하세요.")
    for keyword, (answer, source_id) in FAQ.items():
        if keyword in cleaned:
            return f"{answer} [출처:{source_id}]"
    return "관련 FAQ를 찾지 못했습니다."

이 함수는 짧은 실습용 키워드 검색이다. 동의어나 여러 FAQ가 동시에 포함된 질문은 올바르게 처리하지 못할 수 있다. 바로 그 실패를 평가 사례로 남기고, 문서가 늘어날 때 검색기를 교체한다. FAQ 내용의 날짜는 가상 교육 과정 데이터다.

[app.py]는 함수에 UI만 연결한다(Gradio Interface 가이드).

import gradio as gr
from faq import answer_faq

def respond(question: str) -> str:
    try:
        return answer_faq(question)
    except ValueError as exc:
        return str(exc)

demo = gr.Interface(
    fn=respond,
    inputs=gr.Textbox(label="질문", lines=2),
    outputs=gr.Textbox(label="답변"),
    title="교육 과정 FAQ",
)

if __name__ == "__main__":
    demo.launch()

app.py의 respond는 입력 오류만 사용자 메시지로 바꾼다. 검색기나 모델 장애를 붙일 때 모든 예외를 잡아 같은 문구로 숨기지 않는다. 운영에 공개한다면 인증, 요청량 제한, 로그 보존 정책, 외부 공개 설정을 별도로 검토한다.

하네스 문서와 검사를 연결

AGENTS.md에는 “faq.py는 자료와 답변 규칙, app.py는 UI만 담당한다”, “새 FAQ를 넣을 때 출처 ID를 추가한다”, “자료 없는 질문에는 추측하지 않는다”를 쓴다. QUALITY_SCORE.md에는 아래처럼 확인 가능한 완료 기준을 적는다.

- [ ] 공백·긴 입력을 모델 호출 전에 거절한다.
- [ ] 답변에는 허용된 FAQ의 출처 ID가 있다.
- [ ] 자료가 없는 질문에는 날짜를 생성하지 않는다.
- [ ] 기능 변경 후 단위 테스트와 UI 확인 결과를 남긴다.

이 문서만으로 규칙이 강제되지는 않는다. 예를 들어 아래 검사는 정상 입력·근거 없음·입력 거절을 서로 다른 실패로 다룬다.

import pytest
from faq import answer_faq

def test_known_question_keeps_source():
    assert answer_faq("수업 시간은?") == "월·수 19:00 [출처:FAQ-01]"

def test_unknown_question_does_not_guess():
    assert answer_faq("환불은 언제?") == "관련 FAQ를 찾지 못했습니다."

def test_empty_question_is_rejected():
    with pytest.raises(ValueError):
        answer_faq("   ")

코드가 바뀌면 먼저 이 테스트를 실행하고, 브라우저에서 입력·응답·오류 메시지를 확인한다. git diff로 FAQ 데이터 이외의 파일이 예상 밖으로 수정됐는지 본다. 테스트가 통과해도 “과제 제출”처럼 겹치는 단어가 들어간 새로운 질문은 오분류할 수 있으므로 실패 사례를 더한다. LLM을 붙인 후에는 문자열 정답 테스트만으로는 충분하지 않다. 검색 문서 ID, 인용, 근거 충실성을 따로 평가한다.

하네스 엔지니어링은 ‘경영학’에 가깝다

AI를 어떻게 관리하느냐에 따라 결과물이 달라집니다.

두 가지 실패 유형

1. 지시형 상사
   • 매번 처음부터 모든 맥락을 설명
   • AI가 더 나은 방법을 찾을 공간이 없음
   • 상사(나)의 한계가 팀 결과의 한계가 됨
   • 결과: 상사가 아는 것만 나온다
2. 방임형 상사
   • “알아서 잘해봐” — 맥락이 없음
   • 기준이 없으니 평가도 못함
   • AI는 방향 없이 빠르게 달릴 뿐
   • 결과: 맥락 없는 결과물이 나온다

결론 : 둘 다 AI를 도구처럼 쓰는 것 — 위임이 아니다.

---

위임(Delegation)과 MBO로 보는 하네스 엔지니어링

MBO 단계	하네스 엔지니어링 대응
1. 조직 목표 설정	내가 만들고 싶은 앱/서비스 결정
2. 팀/개인 단위로 쪼개기	하네스 분리 및 업무 단위를 작게 쪼개기
3. 구체적 목표 함께 합의	헌법, 검증 기준을 AI와 공동 작성
4. 실행하며 중간 점검	실행 루프 & 암묵지 문서화
5. 성과 평가 & 반복	결과 확인 → 피드백 → 재수정

분명 테크지만, 본질은 경영학에 가깝다.

---

AI는 나를 조직으로 만든다.

판단력 있는 사람이 AI를 쓰면 팀 전체의 아웃풋을 혼자 낼 수 있게 된다 — Zack Shapiro

기본 조직

• 암묵지가 사람 머릿속에 분산
• 사람이 나가면 지식이 사라짐
• 커뮤니케이션 비용증가
• 규모 = 복잡성

AI가 바꾼 것

• 인지적 병목 제거
• 컨텍스트 윈도우로 전체 파악
• 1인이 팀의 아웃풋을 낼 수 있음
• 개인이 기관을 이길 수 있다

그러나

• 혼자서는 암묵지를 어디에 저장하나? → 하네스

AI는 개인이 팀의 성과를 내게 한다.

개인은 AI와 함께 “조직”을 만든다.