하네스 엔지니어링

개발자 역할의 변화

개발자의 역할은 AI에게 말을 잘 거는 사람에서, AI가 틀릴 수 없는 구조를 짜는 사람으로 진화했다.

AI 개발 초기에는 AI에게 의도를 정확히 전달하는 것이 개발자의 핵심 역량이었다.
이를 프롬프트 엔지니어링이라 부른다.
그런데 AI가 발전하면서, 잘 말하는 것만으로는 부족해졌다.
AI가 참조할 지식의 체계 자체를 설계하는 컨텍스트 엔지니어링이 등장했다.
그러나 이것도 한계가 있었다.
AI는 여전히 실수를 반복했고, 개발자가 매번 개입해야 했다.
그래서 이제는 AI가 애초에 실수할 수 없는 환경을 설계하는 하네스 엔지니어링이 요구된다.
이 흐름이 뒤에서 다룰 모든 개념의 이유가 된다.

하네스 엔지니어링이란

하네스 엔지니어링은 AI의 실수를 개인이 감당하는 것이 아니라, 시스템이 막아내도록 설계하는 일이다.

하네스 엔지니어링은 세 가지 원칙으로 요약된다.
첫째, 잘못된 방향을 원천 차단한다.
둘째, 같은 실수가 반복되지 않도록 방지한다.
셋째, 사람의 간섭 없이 작동하는 자동 시스템을 만든다.
이 원칙은 하나의 핵심 태도에서 나온다.
AI가 실수했을 때 프롬프트를 고치지 말고, 하네스를 고쳐야 한다.
실패가 구조적으로 반복되지 않도록 시스템 자체를 바꾸는 것이 하네스 엔지니어링의 본질이다.
하네스는 문서 설계부터 자동화 파이프라인까지 여러 레이어와 기둥으로 구성된다.
처음부터 모든 것을 세팅하려 하지 말고, 점차 키워나가는 방식이 권장된다.
개인 프로젝트에 맞는 것만 추가하면 되고, 웬만한 기본 구성은 모델 자체에 내장되어 있다.

프로젝트 뇌: docs 설계

docs 폴더는 프로젝트의 뇌 역할을 한다.
세 가지 문서가 핵심이며, "무엇을 → 어떻게 → 왜" 순서로 연결된다.

첫 번째는 PRD.md로, 무엇을 만들지 정의한다.

# PRD: {프로젝트}
 
## 목표
{ 한 줄 요약 }
 
## 핵심 기능
1.
2.
 
## MVP 제외 사항 (프로젝트 규모가 커지면 "범위 외 (Out of Scope)"로 변경)
- { 안 만들 것 }

MVP 제외 사항을 명시하는 것이 특히 중요한데, 설정하지 않으면 AI는 모든 것을 만들려 한다.
MVP는 가볍게 만들어야 하며, 트레이드오프를 명확히 기록하는 것이 핵심이다.

두 번째는 ARCHITECTURE.md로, 어떻게 만들지 정의한다.

# 아키텍처
 
## 디렉터리 구조
{폴더 트리}
 
## 패턴
{디자인 패턴}
 
## 데이터 흐름
{데이터 흐름도}

세 번째는 ADR.md로, 왜 이렇게 만드는지 결정의 근거를 기록한다.

# ADR
 
## ADR-001: {결정}
결정: {선택}
이유: {근거}
트레이드오프: {포기한 것}

기능이 추가될 때는 기존 PRD.md를 계속 업데이트하는 것이 비효율적이다.
추가 기능부터는 docs/features/기능명.md 형태로 기능별 파일을 분리해서 관리한다.
범위가 큰 메뉴 추가처럼 넓은 작업은 아예 새 PRD 파일로 시작하는 것이 맞다.
하네스를 돌릴 때는 "이번 세션은 이 PRD 기준으로만"이라고 범위를 명확히 잡아줘야 한다.

CLAUDE.md 작성법

CLAUDE.md는 AI에게 프로젝트 규칙을 주입하는 파일이다.
처음부터 완벽하게 작성하려 하지 말고, 꼭 보편적으로 항상 적용되는 내용만 담는다.
AI가 생성하게 내버려 두지 말고, 직접 작성해야 한다.

기본 구성 요소는 빌드-테스트 명령어, 디렉터리 구조, 이슈-PR 규칙이다.

# 프로젝트: {프로젝트명}
 
## 기술 스택
- {프레임워크}, {언어}, {주요 라이브러리}
 
## 아키텍처 규칙
- CRITICAL: 모든 API 로직은 app/api 에서만
- CRITICAL: API 키는 환경변수. 하드코딩 금지
 
## 개발 프로세스
- CRITICAL: 새 기능은 테스트를 먼저 작성 (TDD)
- 커밋 메시지: conventional commits (feat: , fix: )
 
## 절대 하지 말아야 할 것들
- 애매한 부분이 생기면 추측하지 말고 무조건 물어봐라.
- 작업 중간에 임의로 다른 방향으로 바꾸지 마라.

CRITICAL 키워드를 붙이면 AI가 일반 규칙보다 우선적으로 따른다.
각 규칙에는 "~~하지 마라"처럼 실수 사례를 함께 적어두는 것이 효과적이다.
TDD 규칙인 "테스트를 먼저 작성하라" 하나만 넣어도 코드 품질이 눈에 띄게 올라간다.
CLAUDE.md에는 현재 상태 요약과 docs 구조 안내만 넣어도, 새 세션마다 AI가 컨텍스트를 빠르게 파악할 수 있다.
AI 기획 단계에서는 충분히 갈궈야 좋은 기획이 나오며, 5번 이상 반복하는 것도 권장된다.
최대한 모든 것을 완벽하게 짠 뒤 자동화하는 방식을 spec-driven development라고 부른다.
이를 위해 spec.json 파일을 만들면 AI가 가장 읽기 쉬운 형식으로 명세를 관리할 수 있다.

상태 관리 & 세션 관리

AI는 작업을 진행하면서 자신이 어디까지 했는지 모를 때가 있다.
이를 해결하기 위해 Phase별로 진행 상태를 JSON 파일에 기록하는 상태 관리가 필요하다.
AI가 그 파일을 읽고 이어서 작업할 수 있기 때문에, 기록 자체가 연속성을 만든다.
긴 작업을 세션에 걸쳐 이어가기 위한 세 가지 구조가 있다.
첫째, progress.txt 같은 인수인계 문서를 만들어 다음 세션이 읽을 수 있게 한다.

둘째, feature_list.json으로 기능 목록을 관리하며 완료 여부를 passes: true / false로 표시한다.

{
  "features": [
    { "name": "로그인", "passes": true },
    { "name": "대시보드", "passes": false }
  ]
}

이 파일이 있으면 작업이 조기 종료되더라도 다음 세션이 어디서부터 이어야 할지 명확하다.
셋째, 포크 기능을 활용해 플랜 설계까지만 진행한 뒤, 포크를 떠서 작업하고 결과만 가져올 수 있다.
세션을 운영하는 핵심 사이클은 네 단계로 이루어진다.
기능 하나 완료 시 커밋 메시지를 자세하게 남기고, 진행 파일을 업데이트한 뒤, 다음 세션을 깔끔한 상태에서 시작하며, 컨텍스트는 40% 이하로 유지한다.
터미널을 여러 개 띄워 병렬로 작업하는 것도 유효한 방법이다.

Hooks — 자동 검증 장치

Hooks는 AI가 실수하기 전에 자동으로 차단하는 장치다.
세 가지 대표적인 훅이 있다.
첫째, TDD 훅은 테스트 없이 구현을 시작하려 하면 작업을 멈춘다.
이 훅 하나로 AI가 구현 전에 반드시 테스트를 먼저 작성하도록 강제할 수 있다.
둘째, Dangerous Cmd Guard는 위험한 커맨드가 실행되지 않도록 막는다.
셋째, Circuit Breaker는 자동화 루프가 무한 반복에 빠지지 않도록 일정 횟수 이상 반복되면 전략을 바꾸도록 개입한다.
실수가 발생할 때마다 린터와 테스트를 추가하고 제약을 늘려나가는 것이, 하네스가 점점 정교해지는 과정이다.

헤드리스 모드 (claude -p)

claude -p는 자동화에 특화된 헤드리스 모드로, 스크립트에서 프로그래밍적으로 Claude를 실행한다.
이 모드를 활용하면 plan → prd → exec → verify → fix로 이어지는 자동 파이프라인을 구성할 수 있다.
OMC처럼 이 파이프라인이 자동으로 돌아가는 구조가 하네스의 완성형에 가깝다.
단, 헤드리스 모드는 모든 Phase마다 새로운 컨텍스트로 시작하기 때문에 대화를 기억하지 못한다.
따라서 앞서 다룬 상태 파일에 진행 상황을 저장하고, 다음 Phase에서 그 파일을 읽는 구조가 필수적이다.
기획과 구현을 최대한 한 세션에서 끝내려는 전략과 결합하면, 최고 품질의 컨텍스트 안에서 작업을 완결할 수 있다.

지속적 개선 루프

프로젝트를 진행하다 보면 나쁜 코드가 자연스럽게 쌓인다.
AI는 기존 코드를 참조하므로, 나쁜 패턴이 있으면 그것을 그대로 복제한다.
이를 막으려면 주기적으로 피드백 루프를 돌려 코드를 리팩토링해야 한다.
안티 패턴 점검, 아키텍처 리뷰 같은 루프를 정기적으로 실행하는 것이 권장된다.
하네스나 문서도 마찬가지로, 관점을 계속 바꾸며 개선점을 요구해야 한다.
사용자 관점, 기획자 관점 등 시각을 달리하면서 점검하는 것이 실제 개발자들도 쓰는 방식이다.
코드를 작성하는 AI와 코드를 리뷰하는 AI를 분리해서 사용하는 것도 품질 향상에 효과적이다.
결국 실수가 생길 때마다 프롬프트가 아니라 하네스를 고치는 것, 이것이 지속적 개선의 핵심 원칙이다.

#개발자 역할의 변화

#하네스 엔지니어링이란

#프로젝트 뇌: docs 설계

#CLAUDE.md 작성법

#상태 관리 & 세션 관리

#Hooks — 자동 검증 장치

#헤드리스 모드 (claude -p)

#지속적 개선 루프