26. AI 업무 하네스 만들기

1. 하네스 폴더 준비

하네스는 프롬프트 한 개가 아니다. AI가 같은 업무를 반복해도 범위와 품질이 흔들리지 않도록 지시, 자료, 절차, 검증, 기록을 함께 둔 작업 환경이다.

프롬프트는 현재 작업의 입력을 개선한다. 하네스는 같은 실수가 반복되지 않도록 작업 환경을 설계한다. 따라서 문서를 모아 두는 것에서 끝나지 않고, 검증에 실패한 결과가 다음 단계로 넘어가지 못하게 해야 한다.

1.1 현재 작업 단계 확인하기

다음 여섯 단계는 하네스의 필요성을 이해하기 위한 성숙도 모형이다. 특정 제품의 공식 등급이 아니라 이 교안에서 사용하는 진단 기준이다.

1단계: 문장이나 코드 일부 자동완성
2단계: 문서나 코드 초안 생성
3단계: 대화하면서 편집
4단계: 한 에이전트가 여러 단계를 계획하고 실행
5단계: 여러 역할이나 에이전트가 나누어 실행
6단계: 정해진 조건에서 높은 자율성으로 반복 실행

4단계처럼 AI가 여러 단계를 스스로 실행하기 시작하면 지시, 권한, 검증, 기록을 함께 관리할 필요가 커진다.

1.2 폴더 구조 만들기

1. "ai_prompt" 폴더에 "26_harness" 폴더를 만든다.
2. 다음 구조를 만든다.

26_harness/
├── 안내.md
├── 지시.md
├── 진행.md
├── input/
├── skills/
├── agents/
├── template/
├── process/
├── check/
├── decision/
├── failure/
└── output/

1. 업무 유형을 한 개 고른다.
   1. 교육 과정 제작
   2. 문서 검수
   3. 최신 정보 조사
   4. 데이터 보고
   5. 콘텐츠 기획
   6. 개발 지원
2. "template"은 반복해서 사용하는 빈 요청서, 보고서 틀, 확인표를 보관하는 폴더이다.
3. 새 작업에서는 원본 양식을 수정하지 않고 복사해서 사용한다.
4. "skills"는 반복해서 사용할 전문 절차를 보관한다.
5. "agents"는 역할별 입력, 도구, 출력, 금지 규칙을 보관한다.

2. 업무 안내 작성하기

2.1 목적과 경계 고정하기

1. "안내.md"에 다음 내용을 입력한다.

# 업무 안내

업무 이름:
업무 목적:
대상:
최종 결과물:
사용할 입력:
사용하지 않을 입력:
허용 도구:
금지 도구:
사람이 확인할 지점:
완료 조건:

1. 목표와 상관없는 도구를 제거한다.
2. 외부 전송, 삭제, 덮어쓰기는 기본 금지로 둔다.

3. 지시와 절차 분리하기

3.1 항상 지키는 규칙 작성하기

1. "지시.md"에 다음 내용을 입력한다.

# 작업 지시

- input 폴더의 자료만 입력으로 사용한다.
- 원자료는 수정하지 않는다.
- 확인되지 않은 날짜와 수치는 만들지 않는다.
- 개인정보와 기밀을 발견하면 중단한다.
- 중간 결과는 output 폴더에 새 파일로 저장한다.
- 기존 결과 파일을 덮어쓰기 전에 확인한다.
- 각 주장에 근거 파일을 표시한다.
- 완료 후 check 폴더의 검증 절차를 실행한다.

1. 특정 작업 순서는 "process/작업절차.md"에 작성한다.
2. 지시 파일에는 항상 지킬 규칙만 남긴다.
3. 여러 업무에서 반복할 전문 절차는 "skills"의 별도 SKILL.md로 분리한다.
4. 조사자나 검토자처럼 독립된 역할은 "agents"에 역할별 지침으로 분리한다.

3.2 작업 절차 작성하기

1. "process/작업절차.md"에 다음 순서를 입력한다.

1. 안내.md와 지시.md 읽기
2. 진행.md에서 현재 상태 확인
3. input 폴더의 파일 목록 확인
4. 필수 입력과 위험 정보 확인
5. 작업 계획 작성
6. 승인된 단계만 실행
7. 중간 결과 저장
8. 검증 절차 실행
9. 사람이 최종 확인
10. 진행.md 갱신

1. 상태가 달라질 때 이동할 단계를 적는다.

필수 입력 없음 → 중단
위험 정보 발견 → 중단하고 기록
검증 실패 → 결과 작성 단계로 복귀
검증 통과 → 사람 확인
사람 승인 → 완료 기록

1. 각 중간 결과를 체크포인트로 기록해 실패한 단계부터 다시 시작한다.

4. 검증 절차 만들기

4.1 필수 확인 항목 작성하기

1. "check/검증.md"를 만든다.
2. 다음 내용을 입력한다.

# 결과 검증

- 결과 파일이 output 폴더에 있는가
- 원자료가 변경되지 않았는가
- 필수 구역이 모두 있는가
- 근거 파일을 표시했는가
- 입력에 없는 사실을 추가하지 않았는가
- 개인정보와 기밀이 없는가
- 날짜와 계산을 다시 확인했는가
- 미확인 항목을 따로 표시했는가

1. 업무에 맞는 항목을 추가한다.
2. 확인할 수 없는 항목을 자동으로 확인 처리하지 않는다.
3. 필수 항목에 하나라도 문제가 있으면 결과를 완료로 처리하지 않는다.
4. 문제를 수정한 뒤 검증을 다시 실행한다.

4.2 검증을 통과 조건으로 사용하기

작업을 시작하기 전에 다음 요청문을 사용한다.

작업을 실행하기 전에 안내.md와 지시.md의 허용·금지 규칙을 점검한다.
위반 가능성이 있거나 필요한 입력이 없으면 실행하지 말고 이유를 알린다.

결과를 만든 뒤 check/검증.md의 필수 항목을 확인한다.
하나라도 문제가 있으면 완료로 기록하지 않는다.
문제 위치와 수정할 내용을 제시한다.

5. 진행과 결정 기록하기

5.1 진행 파일 작성하기

1. "진행.md"에 다음 내용을 입력한다.

# 진행 상태

마지막 수정일:
완료:
진행 중:
다음 작업:
막힌 문제:
생성한 파일:
검증 결과:

1. 중요한 선택은 "decision" 폴더에 남긴다.
2. 반복된 오류는 "failure" 폴더에 남긴다.
3. 해결되지 않은 문제를 완료로 적지 않는다.

6. 작은 업무로 시험하기

6.1 연습 자료 넣기

1. 개인정보가 없는 짧은 입력 파일을 "input"에 넣는다.
2. AI 에이전트에 "안내.md", "지시.md", "진행.md", "process/작업절차.md"를 제공한다.
3. 다음 요청문을 입력한다.

먼저 안내, 지시, 진행, 작업 절차를 읽는다.
지금은 실행하지 않는다.

다음 내용만 제시한다.
1. 이해한 목표
2. 사용할 입력 파일
3. 필요한 도구와 권한
4. 실행할 작업 순서
5. 중단 조건
6. 만들 결과 파일
7. 실행할 검증

1. 계획이 하네스 규칙과 일치하는지 확인한다.
2. 읽기 단계부터 순서대로 승인한다.
3. 결과를 "output"에 저장한다.
4. "check/검증.md"를 사용해 확인한다.
5. "진행.md"를 갱신한다.

7. 새 대화에서 다시 실행하기

7.1 기록만으로 이어가기

1. 새 대화를 시작한다.
2. 하네스의 안내, 지시, 진행, 절차, 검증 파일을 제공한다.
3. 이전 대화 내용은 제공하지 않는다.
4. 다음 작업과 필요한 입력을 물어본다.
5. AI가 현재 상태를 정확히 읽는지 확인한다.
6. 같은 규칙과 파일 구조를 유지하는지 확인한다.

8. Claude Code를 선택한 경우

8.1 개발 지원 하네스로 바꾸기

1. 프로젝트 루트의 지시 파일에 저장소 구조와 검사 명령을 적는다.
2. 코드 스타일은 문장 지시만 쓰지 않고 린터와 타입 검사로 확인한다.
3. 기능 수정 전 실패 재현과 테스트 방법을 정한다.
4. 명령 실행과 파일 수정 권한을 분리한다.
5. 진행 상태, 결정 이유, 실패 기록을 프로젝트 문서에 남긴다.
6. Claude Code의 현재 설치법과 기능명은 공식 문서에서 다시 확인한다.

9. 오류가 생겼을 때

9.1 새 대화에서 규칙을 놓친 경우

1. 지시 파일이 너무 길거나 충돌하는지 확인한다.
2. 항상 지킬 규칙만 짧게 남긴다.
3. 세부 절차는 별도 파일로 분리한다.
4. 중요한 규칙은 검증 절차와 권한 설정으로 보완한다.

9.2 기록과 실제 결과가 다른 경우

1. 실제 파일 상태를 기준으로 확인한다.
2. 진행 파일을 고친다.
3. 차이가 생긴 원인을 실패 기록에 남긴다.
4. 다음 실행 전에 같은 문제를 막을 규칙을 추가한다.

10. 자신의 업무에 적용하기

1. 업무 유형 한 개를 고른다.
2. 하네스 폴더 구조를 만든다.
3. 안내, 지시, 절차, 검증, 진행 파일을 작성한다.
4. 작은 입력으로 한 번 실행한다.
5. 새 대화에서 기록 파일만으로 이어서 실행한다.
6. 반복된 문제를 규칙과 검증 절차에 반영한다.

11. 작업 환경 정기 정리하기

11.1 주간 점검하기

1. 일주일에 한 번 다음 항목을 확인한다.

- 실제 상태와 설명이 다른 오래된 문서
- temp_로 시작하거나 _old로 끝나는 임시 파일
- 더 이상 사용하지 않는 입력 자료와 양식
- 진행.md의 기록과 실제 output 파일의 차이
- 해결됐지만 미해결로 남은 실패 기록

1. 삭제가 필요한 파일은 바로 지우지 않고 별도 보관 폴더로 옮길 대상을 먼저 정한다.
2. 기록과 실제 상태가 다르면 실제 파일을 기준으로 기록을 고친다.
3. 개발 도구를 사용하는 경우 린터, 테스트, 타입 검사, 자동 검사로 검증과 정리를 강화할 수 있다.

12. 예상 결과와 맞춰보기

계획 확인: 허용된 입력과 도구만 사용함
검증 결과:
- 결과 파일 위치: 확인
- 원자료 보존: 확인
- 필수 구역: 확인
- 근거 표시: 문제

처리: 근거 표시를 수정하기 전까지 완료로 기록하지 않음

검증에서 문제가 발견된 결과가 완료 처리되지 않고, 수정 후 다시 검증되면 정상이다.

13. 살펴보기

• 프롬프트 입력과 작업 환경의 차이를 설명할 수 있는가
• 안내·지시·절차·검증·진행 기록의 역할이 구분되는가
• 반복 절차를 스킬로, 독립 역할을 에이전트 지침으로 분리했는가
• 상태 분기와 체크포인트가 작업 절차에 연결되는가
• template 폴더의 양식을 복사해서 사용하는가
• 필수 검증 실패 결과를 완료 처리하지 않는가
• 실제 상태와 다른 기록과 임시 파일을 정기적으로 정리하는가
• 개발 적용 시 별도 기초 교안과 검사 도구를 연결했는가

14. 적용 전 확인

• 지시, 자료, 절차, 검증, 기록이 하나의 작업 흐름으로 연결돼 있는지 확인한다.
• 검증을 통과하지 못한 결과는 완료 처리하지 않는다.
• 도구 기능명과 실행 방법은 사용하는 환경에서 다시 확인한다.