AI 업무 하네스 만들기

작성자:

이 교안은 프롬프트 엔지니어링 시리즈의 종합 캡스톤으로, 앞서 익힌 기록 관리와 결과 검증을 한데 묶어 지시·자료·절차·검증·기록이 하나의 작업 흐름으로 도는 AI 업무 하네스를 직접 만든다. 컴퓨터에서 폴더와 텍스트 파일을 만들 수 있고, 앞 교안의 기록 구조와 검증 기준을 다뤄 봤으면 따라올 수 있다. 끝까지 따라 하면 검증을 통과하지 못한 결과가 다음 단계로 넘어가지 못하게 막는 한 벌의 작업 환경과, 새 대화에서도 같은 규칙으로 업무를 이어가는 운영 방식이 손에 남는다.

[!INFO]
개발 환경과 코드 기초는 별도 교안에서 학습한다. 개발 지원 하네스는 해당 기초 내용을 학습한 뒤 적용한다.

1 – 하네스 폴더 준비

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

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

1.1 – 현재 작업 단계 확인하기

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

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

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

1.2 – 폴더 구조 만들기

  1. "ai_prompt" 폴더에 "26_harness" 폴더를 만든다.
  2. 다음 구조를 만든다.
26_harness/
├── guide.md
├── instructions.md
├── progress.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. "guide.md"에 다음 내용을 입력한다.
# 업무 안내

업무 이름:
업무 목적:
대상:
최종 결과물:
사용할 입력:
사용하지 않을 입력:
허용 도구:
금지 도구:
사람이 확인할 지점:
완료 조건:
  1. 목표와 상관없는 도구를 제거한다.
  2. 외부 전송, 삭제, 덮어쓰기는 기본 금지로 둔다.

3 – 지시와 절차 분리하기

3.1 – 항상 지킬 규칙 작성하기

  1. "instructions.md"에 다음 내용을 입력한다.
# 작업 지시

- input 폴더의 자료만 입력으로 사용한다.
- 원자료는 수정하지 않는다.
- 확인되지 않은 날짜와 수치는 만들지 않는다.
- 개인정보와 기밀을 발견하면 중단한다.
- 중간 결과는 output 폴더에 새 파일로 저장한다.
- 기존 결과 파일을 덮어쓰기 전에 확인한다.
- 각 주장에 근거 파일을 표시한다.
- 완료 후 check 폴더의 검증 절차를 실행한다.
  1. 특정 작업 순서는 "process/steps.md"에 작성한다.
  2. 지시 파일에는 항상 지킬 규칙만 남긴다.
  3. 여러 업무에서 반복할 전문 절차는 "skills"의 별도 SKILL.md로 분리한다.
  4. 조사자나 검토자처럼 독립된 역할은 "agents"에 역할별 지침으로 분리한다.

3.2 – 작업 절차 작성하기

  1. "process/steps.md"에 다음 순서를 입력한다.
1. guide.md와 instructions.md 읽기
2. progress.md에서 현재 상태 확인
3. input 폴더의 파일 목록 확인
4. 필수 입력과 위험 정보 확인
5. 작업 계획 작성
6. 승인된 단계만 실행
7. 중간 결과 저장
8. 검증 절차 실행
9. 사람이 최종 확인
10. progress.md 갱신
  1. 상태가 달라질 때 이동할 단계를 적는다.
필수 입력 없음 → 중단
위험 정보 발견 → 중단하고 기록
검증 실패 → 결과 작성 단계로 복귀
검증 통과 → 사람 확인
사람 승인 → 완료 기록
  1. 각 중간 결과를 체크포인트로 기록해 실패한 단계부터 다시 시작한다.

4 – 검증 절차 만들기

4.1 – 필수 확인 항목 작성하기

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

- 결과 파일이 output 폴더에 있는가
- 원자료가 변경되지 않았는가
- 필수 구역이 모두 있는가
- 근거 파일을 표시했는가
- 입력에 없는 사실을 추가하지 않았는가
- 개인정보와 기밀이 없는가
- 날짜와 계산을 다시 확인했는가
- 미확인 항목을 따로 표시했는가
  1. 업무에 맞는 항목을 추가한다.
  2. 확인할 수 없는 항목을 자동으로 확인 처리하지 않는다.
  3. 필수 항목에 하나라도 문제가 있으면 결과를 완료로 처리하지 않는다.
  4. 문제를 수정한 뒤 검증을 다시 실행한다.

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

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

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

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

5 – 진행과 결정 기록하기

5.1 – 진행 파일 작성하기

  1. "progress.md"에 다음 내용을 입력한다.
# 진행 상태

마지막 수정일:
완료:
진행 중:
다음 작업:
막힌 문제:
생성한 파일:
검증 결과:
  1. 중요한 선택은 "decision" 폴더에 남긴다.
  2. 반복된 오류는 "failure" 폴더에 남긴다.
  3. 해결되지 않은 문제를 완료로 적지 않는다.

6 – 작은 업무로 시험하기

6.1 – 연습 자료 넣기

  1. 개인정보가 없는 짧은 입력 파일을 "input"에 넣는다.
  2. AI 에이전트에 "guide.md", "instructions.md", "progress.md", "process/steps.md"를 제공한다.
  3. 다음 요청문을 입력한다.

[!INFO]
일반 웹 AI에서는 필요한 파일 내용을 대화창에 붙여 넣고 결과를 사람이 output 폴더에 저장한다. 파일을 직접 읽고 쓰는 기능이 있을 때만 작업 폴더 권한을 허용한다.

먼저 guide.md, instructions.md, progress.md, process/steps.md를 읽는다.
지금은 실행하지 않는다.

다음 내용만 제시한다.
1. 이해한 목표
2. 사용할 입력 파일
3. 필요한 도구와 권한
4. 실행할 작업 순서
5. 중단 조건
6. 만들 결과 파일
7. 실행할 검증
  1. 계획이 하네스 규칙과 일치하는지 확인한다.
  2. 읽기 단계부터 순서대로 승인한다.
  3. 결과를 "output"에 저장한다.
  4. "check/verify.md"를 사용해 확인한다.
  5. "progress.md"를 갱신한다.

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

7.1 – 기록만으로 이어가기

  1. 새 대화를 시작한다.
  2. 하네스의 guide.md, instructions.md, progress.md, process/steps.md, check/verify.md 파일을 제공한다.
  3. 이전 대화 내용은 제공하지 않는다.
  4. 다음 작업과 필요한 입력을 물어본다.
  5. AI가 현재 상태를 정확히 읽는지 확인한다.
  6. 같은 규칙과 파일 구조를 유지하는지 확인한다.

[!WARNING]

  1. 새 대화에서 규칙을 놓치면 지시 파일이 너무 길거나 충돌하는지 확인하고, 항상 지킬 규칙만 짧게 남긴 뒤 세부 절차는 별도 파일로 분리한다.
  2. 중요한 규칙은 검증 절차와 권한 설정으로 보완한다.
  3. 기록과 실제 결과가 다르면 실제 파일 상태를 기준으로 진행 파일을 고치고, 차이가 생긴 원인을 실패 기록에 남긴 뒤 다음 실행 전에 같은 문제를 막을 규칙을 추가한다.

8 – Claude Code를 선택한 경우

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

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

9 – 규칙을 자동으로 실행하기

9.1 – 훅이 필요한 이유

지금까지 만든 지시와 검증은 사람이 요청문으로 불러야 작동한다. 요청문을 빠뜨리거나 AI가 규칙을 잊으면 검증을 거치지 않은 결과가 다음 단계로 넘어간다.

훅은 정해진 순간에 자동으로 실행되는 규칙이다. AI의 기억에 의존하지 않고 작업 환경이 규칙을 강제한다. 요청문이 검증을 실행해 줘라는 부탁이라면, 훅은 결과를 만들면 검증이 자동으로 실행된다는 강제이다.

9.2 – 훅을 거는 시점

이벤트는 작업 흐름에서 훅이 실행되는 시점이다. 자주 쓰는 시점은 다음과 같다.

대화 시작 시: guide.md, instructions.md, progress.md를 자동으로 읽는다.
도구 사용 직전: 외부 전송, 삭제, 덮어쓰기 같은 위험한 동작을 미리 막는다.
도구 사용 직후: 결과가 지시 규칙을 지켰는지 확인한다.
응답 종료 직전: check/verify.md 실행과 progress.md 갱신 여부를 확인한다.

도구 사용 직전 시점에서 위험한 동작을 막으면, instructions.md에 적은 외부 전송, 삭제, 덮어쓰기 기본 금지가 사람의 확인 없이도 지켜진다.

9.3 – 훅이 동작하는 환경

훅은 파일을 직접 읽고 명령을 실행하는 도구 환경에서 동작한다. Claude Code가 이 기능을 제공한다.

일반 웹 AI에는 자동 실행 기능이 없다. 이때는 4.2의 통과 조건 요청문과 사람 확인으로 같은 목적을 대신한다.

9.4 – 훅 예제 작성하기

다음은 Claude Code에서 삭제 명령을 도구 실행 직전에 막는 예제이다.

이 스크립트는 jq 가 필요하다. jq 가 없으면 검사가 무력화될 수 있으니 설치하거나, jq 미설치 시 안전하게 차단(fail-closed)되도록 작성한다.

  1. 프로젝트의 ".claude/settings.json"에 도구 사용 직전 이벤트와 검사 스크립트를 연결한다.
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": ".claude/hooks/check.sh" }
        ]
      }
    ]
  }
}
  1. ".claude/hooks/check.sh"에 검사 내용을 작성한다.
#!/bin/bash
input=$(cat)
cmd=$(echo "$input" | jq -r '.tool_input.command // empty')

if <kbd>"$cmd" =~ ^rm</kbd>; then
  echo "차단: 삭제 명령은 허용하지 않는다" >&2
  exit 2
fi
exit 0
  1. 스크립트에 실행 권한을 준다.
chmod +x .claude/hooks/check.sh
  1. 각 항목의 뜻은 다음과 같다.
    1. "PreToolUse"는 도구를 실행하기 직전 시점이다.
    2. "matcher"는 검사할 도구 이름이다. 여기서는 명령을 실행하는 "Bash" 도구만 검사한다.
    3. 스크립트는 실행될 명령을 입력으로 받아 검사하고, 삭제 명령이면 종료 코드 2를 돌려준다.
    4. 종료 코드 2는 도구 실행을 막으라는 신호이고, 0은 그대로 진행하라는 신호이다.

[!INFO]
훅 이벤트 이름과 설정 항목은 도구 버전에 따라 달라진다. 현재 이벤트 이름과 설정 구조는 Claude Code 공식 문서에서 다시 확인한다.

[!WARNING]

  1. 검사할 수 없는 항목을 자동으로 통과시키지 않는다. 차단 조건을 명확히 적고, 판단이 안 되면 진행하지 않게 한다.
  2. 훅 하나에 너무 많은 검사를 넣으면 작업이 자주 멈춘다. 위험한 동작부터 최소한으로 막고 점차 늘린다.
  3. 종료 코드를 반대로 적지 않는다. 차단은 2, 진행은 0이며 두 값을 바꾸면 위험한 동작이 그대로 실행된다.

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

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

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

11.1 – 주간 점검하기

  1. 일주일에 한 번 다음 항목을 확인한다.
- 실제 상태와 설명이 다른 오래된 문서
- temp_로 시작하거나 _old로 끝나는 임시 파일
- 더 이상 사용하지 않는 입력 자료와 양식
- progress.md의 기록과 실제 output 파일의 차이
- 해결됐지만 미해결로 남은 실패 기록
  1. 삭제가 필요한 파일은 바로 지우지 않고 별도 보관 폴더로 옮길 대상을 먼저 정한다.
  2. 기록과 실제 상태가 다르면 실제 파일을 기준으로 기록을 고친다.
  3. 개발 도구를 사용하는 경우 린터, 테스트, 타입 검사, 자동 검사로 검증과 정리를 강화할 수 있다.

12 – 예상 결과와 맞춰보기

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

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

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

[!INFO]
아홉 항목 중 일곱 항목 이상을 만족하면 정상이다.

  1. 프롬프트 입력과 작업 환경의 차이를 설명할 수 있다.
  2. 안내·지시·절차·검증·진행 기록의 역할이 구분된다.
  3. 반복 절차를 스킬로, 독립 역할을 에이전트 지침으로 분리했다.
  4. 상태 분기와 체크포인트가 작업 절차에 연결된다.
  5. 규칙을 자동으로 강제하는 훅의 시점과 차단 신호를 구분한다.
  6. template 폴더의 양식을 복사해서 사용한다.
  7. 필수 검증 실패 결과를 완료 처리하지 않는다.
  8. 실제 상태와 다른 기록과 임시 파일을 정기적으로 정리한다.
  9. 개발 적용 시 별도 기초 교안과 검사 도구를 연결했다.

13 – 막히면 AI 코치에게 묻기

이 문서에서 익힌 지시·자료·절차·검증·기록을 묶은 AI 업무 하네스를 만드는 법을 내 상황에 적용하다 막히면, 아래를 대화형 AI(ChatGPT·Claude·Gemini)에 붙여 넣어 실습 코치로 삼는다. 답을 한꺼번에 받지 말고 한 단계씩 풀어 간다.

너는 AI 업무 하네스 설계 실습 코치다. 나는 guide·instructions·process·check·progress 파일로 같은 업무가 흔들리지 않는 작업 환경을 만들고 검증을 통과 조건으로 거는 법, 훅으로 규칙을 자동 강제하는 법을 배웠고, 내 업무 유형 하나의 하네스를 만들어 작은 입력으로 한 번 돌리는 실습을 직접 완성하려 한다. 답을 통째로 주지 말고 한 단계씩 물어 내가 직접 하게 한다.

[코칭 방식]
1. 먼저 내가 고른 업무 유형과 지금까지 만든 하네스 파일을 묻는다.
2. 막힌 원인을 한 가지 짚어 준다. 완성된 파일 내용이나 검증 절차를 통째로 주지 않는다.
3. 다음 한 단계만 제시하고, 내가 해 본 결과를 말하면 확인 질문을 던진다.
4. 마지막에 검증 실패 결과가 완료로 처리되지 않고 수정 후 재검증되는지 점검 질문을 한다.

[내 상황]
- 지금까지 한 것: {한것}
- 막힌 지점·메시지: {막힌점}
- 내 소재: {소재}

준비됐으면 "고른 업무 유형과 지금 만든 하네스 파일은 무엇무엇인가?"라고만 답한다.
  1. {한것} – 지금까지 진행한 단계, 예: 26_harness 폴더 구조와 guide.md, instructions.md를 만들었다.
  2. {막힌점} – 막힌 부분이나 받은 메시지, 예: check/verify.md의 항목을 통과 조건으로 어떻게 거는지 모르겠다.
  3. {소재} – 적용할 내 자료·주제, 예: 문서 검수 업무 유형으로 하네스 만들기.

채운 예시 한 벌은 이렇다.

너는 AI 업무 하네스 설계 실습 코치다. 나는 guide·instructions·process·check·progress 파일로 같은 업무가 흔들리지 않는 작업 환경을 만들고 검증을 통과 조건으로 거는 법, 훅으로 규칙을 자동 강제하는 법을 배웠고, 내 업무 유형 하나의 하네스를 만들어 작은 입력으로 한 번 돌리는 실습을 직접 완성하려 한다. 답을 통째로 주지 말고 한 단계씩 물어 내가 직접 하게 한다.

[코칭 방식]
1. 먼저 내가 고른 업무 유형과 지금까지 만든 하네스 파일을 묻는다.
2. 막힌 원인을 한 가지 짚어 준다. 완성된 파일 내용이나 검증 절차를 통째로 주지 않는다.
3. 다음 한 단계만 제시하고, 내가 해 본 결과를 말하면 확인 질문을 던진다.
4. 마지막에 검증 실패 결과가 완료로 처리되지 않고 수정 후 재검증되는지 점검 질문을 한다.

[내 상황]
- 지금까지 한 것: 26_harness 폴더 구조와 guide.md, instructions.md를 만들었다.
- 막힌 지점·메시지: check/verify.md의 항목을 작업 통과 조건으로 어떻게 거는지 모르겠다.
- 내 소재: 문서 검수 업무 유형으로 하네스 만들기.

준비됐으면 "고른 업무 유형과 지금 만든 하네스 파일은 무엇무엇인가?"라고만 답한다.

[!TIP]

  1. 코치가 답을 통째로 주려 하면 "한 단계씩 물어라"라고 다시 요청한다.
  2. 내 상황을 적을 때 항상 지킬 규칙(instructions)과 이번 작업 순서(process)를 섞지 않았는지 빠뜨리지 않는다.

댓글 남기기