인박스 정리를 하네스 계약으로 만들고, 실행 영수증까지 발행했다
2026.08.08
한 줄 요약
자료를 그때그때 옮기던 AKM 인박스 처리를 Goal / Trigger / Context / Route / Criteria / Approval / Repair 계약으로 정리하고, 실제 PDF 한 건을 분류한 뒤 Trace / Proof / Verdict / Repair 실행 영수증으로 완료를 증명했다.
이런 분들께 도움돼요
Obsidian이나 폴더 기반 지식관리 시스템의 인박스가 계속 쌓이는 분
AI에게 자료 정리를 맡기고 있지만 매번 분류 결과가 달라 불안한 분
“처리했습니다”라는 답보다 실제 파일과 검증 기록을 확인하고 싶은 분
에이전트 하네스를 거창한 시스템이 아니라 작은 실제 업무에 적용해 보고 싶은 분
1. 무슨 업무인가
내 my-akm에는 자료의 역할에 따라 00-inbox, 10-sources, 20-knowledge, 50-procedures, 60-actions, 70-evaluation, 80-outputs 같은 레이어가 있다. 구조 자체는 이미 있었지만, 인박스에 새 자료가 들어왔을 때 실제 처리는 매번 조금씩 달랐다.
어떤 날은 원본만 옮겼고, 어떤 날은 요약문까지 만들었다. 한글 자료가 영어로 정리되기도 했고, 처리가 끝난 뒤 인벤토리가 갱신됐는지 다시 물어봐야 했다. 파일이 적을 때는 사람이 확인할 수 있었지만, 자료가 늘어나자 “무엇을 어디까지 해야 완료인가”가 필요해졌다.
이번에 하려던 일은 단순했다.
인박스 분류를 한 번 요청하면, 에이전트가 정해진 기준으로 자료를 읽고 분류하고, 원본과 파생 문서를 연결하고, lint와 인벤토리 갱신까지 마친 뒤 실행 증거를 남기게 한다.
여기서 자동은 상시 감시나 예약 실행을 뜻하지 않는다. 현재는 사용자의 인박스 분류 요청이 Trigger가 되고, 그 뒤의 판독·라우팅·저장·검증이 계약된 순서로 실행되는 구조다.
2. 설계 계약
지아코모 WEEK3 강의의 일곱 칸을 기준으로 AKM 하네스 운영 계약을 만들었다.
항목 | my-akm에 정한 내용 |
|---|---|
Goal | 인박스 자료를 안전하게 식별·분류하고 원본, 로그, lint, 인벤토리까지 추적 가능하게 남긴다. |
Trigger | 사용자가 인박스 처리나 특정 Skill 실행을 요청할 때 시작한다. |
Context | 하네스 계약, 라우팅 규칙, 자료 수집 절차, 원본 파일과 기존 AKM 문서를 근거로 읽는다. |
Tree / Route | 입력 확인 → 성격·언어 판별 → 중복 검사 → 원본 보존 → source/knowledge/action 라우팅 → lint → 인벤토리 → 완료 판정 순으로 실행한다. |
Criteria | 출처와 성격 식별, 올바른 경로, 원본 연결, 실행 로그, lint 통과, 인벤토리 갱신, 인박스 중복 제거를 확인한다. |
Approval | 삭제, 외부 게시, 채점, 모호한 분류와 같은 의미 있는 행동은 사용자 승인 없이 실행하지 않는다. |
Repair | 실패하면 전체를 다시 처리하지 않고 깨진 가장 작은 단계만 수정한 뒤 같은 기준으로 재검사한다. |
실행 흐름은 다음처럼 잡았다.
사용자 요청
→ 입력 Gate
→ 자료 성격·언어·중복 확인
→ 레이어 라우팅
→ 원본과 파생 문서 연결
→ 실행 로그
→ lint
→ 인벤토리 갱신
→ 완료 Gate
→ 실행 영수증자동화의 금지선도 계약에 넣었다. 파일이 들어왔다는 이유만으로 논술 채점 Skill을 실행하지 않고, 원본을 덮어쓰거나 자료를 자동 삭제하지 않으며, 외부 게시도 하지 않는다. 자동화가 커질수록 “무엇을 하는가”만큼 “무엇을 하지 않는가”가 중요하다고 판단했다.
3. 어디서 막혔나
첫 번째로 막힌 지점은 자동 분류라는 말의 범위였다. 나는 인박스에 파일을 넣으면 알아서 정리되기를 원했지만, 그것이 파일 감시기가 상시 대기하는 것인지, 사용자가 한 번 요청한 뒤 전체 절차가 자동으로 이어지는 것인지 구분하지 않았다.
현재 필요한 것은 후자였다. 강의 자료에서도 상시 자동 실행, 예약, 외부 서비스 변경이나 복잡한 그래프는 기본과제에 필요하지 않다고 했다. 그래서 우선은 사용자의 요청을 명확한 Trigger로 두고, 요청 이후의 작업만 workflow로 고정했다.
두 번째 막힘은 방법론 문서와 실행 영수증의 혼동이었다. 처음에는 20-knowledge의 Proof, Gate, Eval, Repair 및 실행 영수증 패턴이 영수증처럼 보였다. 하지만 이 파일은 영수증을 어떻게 만들지 설명하는 지식 문서였다. 실제 실행 영수증은 특정 실행 ID, 입력, 산출물, 판정과 수리 기록을 가진 별도 파일이어야 했다.
세 번째 막힘은 실제 lint에서 나왔다. WEEK3 PDF를 분류한 뒤 첫 검사를 실행하자 오류는 없었지만 경고가 2건 발생했다.
source note에 lint가 인식하는
요약섹션이 없었다.action log의
처리 결과제목이 lint 표준결과와 일치하지 않았다.
내용은 맞았지만 시스템이 기대하는 인터페이스와 문서 제목이 어긋난 것이다.
4. 무엇을 바꿨나
먼저 00-system/AKM-HARNESS-CONTRACT.md를 공식 계약으로 발효했다. 사람용 시작 화면인 AKM-NAVIGATOR.md와 에이전트 시작 인덱스인 AKM-INDEX.md에도 연결해, 인박스 분류나 Skill 실행 전에 이 계약을 찾을 수 있게 했다.
그다음 인박스에 있던 GPTERS23-Agent-Harness-WEEK3-deck-v1.5.pdf를 가장 작은 정상 실행 대상으로 삼았다. 에이전트가 PDF 전체 43페이지를 읽고 다음처럼 분류했다.
원본 PDF
→ 10-sources/personal/originals/
검색 가능한 한국어 정리본
→ 10-sources/personal/
실행·분류 기록
→ 60-actions/
기존 개념 보강
→ 20-knowledge/
실행 영수증
→ 70-evaluation/lint 경고는 가장 작은 단위로 수리했다. source note에 ## 요약을 추가하고, action log의 ## 처리 결과를 ## 결과로 바꿨다. 문서 전체를 다시 쓰거나 기준을 바꾸지 않았다. 같은 lint를 다시 실행해 오류 0건, 경고 0건을 확인했다.
5. 실행 영수증
실행 영수증은 하나의 파일로 저장했다. 실행 영수증 안에는 실행 순서를 기록한 Trace, 완료 증거를 모은 Proof, 기준별 통과 여부를 판정한 Verdict, 문제의 수정과 재검사를 기록한 Repair가 들어 있다.
Trace
인박스 조회부터 계약·절차 read, 중복 검사, PDF 43페이지 판독, 원본 이동, source note와 action log 생성, 기존 지식 보강, lint와 인벤토리 갱신까지 실제 실행 순서를 기록했다.
Proof
다음 파일과 상태를 실행 증거로 연결했다.
보존된 원본 PDF와 SHA-256
원본 경로와 읽은 범위가 적힌 한국어 source note
분류 이유가 적힌 action log
보강된 기존 지식 노트
W3 항목이 추가된 지아코모 강의 자료 허브
갱신된 AKM 인벤토리
.gitkeep만 남은 인박스 상태최종 lint 오류 0건, 경고 0건
Verdict
계약에서 정한 일곱 기준을 각각 판정했다.
기준 | 판정 |
|---|---|
자료 식별 | PASS |
올바른 라우팅 | PASS |
출처 연결 | PASS |
실행 기록 | PASS |
lint | PASS |
인벤토리 갱신 | PASS |
인박스 완료 | PASS |
최종 판정은 PASS였다. 확인하지 못한 기준을 빈칸이나 통과로 처리하지 않았고, 이번 실행에서 적용되지 않은 Skill 자동 실행과 외부 게시도 하지 않았다고 명시했다.
Repair
첫 lint의 경고 2건과 수정 내용을 그대로 남겼다. 요약 섹션 추가와 결과 제목 정규화만 수행한 뒤 같은 기준으로 다시 검사했다. 실패가 없었던 것처럼 지우지 않고, 무엇이 깨졌고 무엇만 고쳤는지를 영수증에 포함했다.
6. 무엇이 달라졌나
이전에는 인박스 처리가 끝났다는 에이전트의 말에 의존해야 했다. 이제는 정상 완료 여부를 파일로 확인할 수 있다.
이전
인박스 파일 → 에이전트가 판단해서 이동 → “처리 완료”
이후
인박스 파일
→ 계약된 Trigger와 Route
→ 원본·정리본·로그
→ lint와 인벤토리
→ 기준별 Verdict
→ 실행 영수증가장 크게 달라진 점은 자동화가 단순한 파일 이동이 아니라 권한과 완료 조건이 있는 업무가 되었다는 것이다. 에이전트는 자료를 분류할 수 있지만, 삭제하거나 게시하거나 논술 채점을 시작할 권한까지 자동으로 얻지는 않는다. 반대로 분류를 완료했다고 말하려면 원본 연결, lint, 인벤토리와 인박스 상태를 증거로 보여줘야 한다.
이번 실행으로 하네스 계약과 실행 영수증이 실제 파일로 연결되었다. 방법론 문서, 실제 작업 로그, 검증 결과도 각자의 레이어에 따로 남았다. 다음에 문제가 생기면 대화 기억에 의존하지 않고 어느 단계에서 어긋났는지 돌아볼 수 있다.
로그인하고 댓글을 남겨 주세요
에이전트 하네스 개념을 실제 인박스 정리에 깔끔하게 녹여내신 과정
인박스가 다양하게 쓸수있어서 인박스에 저장된걸 다른 봇에 넘겨주고 일한다던지 등등 너무 좋습니다
세 번째 막힘이 오래 남습니다. 내용은 맞는데 검사기가 경고 2건을 냈고, 원인은 문서 제목이 시스템이 기대하는 이름과 달랐던 것이었다고요. 처리 결과를 결과로요.
고칠 때도 그 두 줄만 건드리셨더군요. 내용이 맞다고 통과되는 게 아니라 약속한 모양이어야 통과된다는 걸 두 줄로 보여준 자리였습니다. 사람 눈에는 같은 말인데 검사기에는 다른 말이었네요. 저도 여기서 자주 걸립니다.
확인하지 못한 기준을 빈칸이나 통과로 적지 않으셨다는 문장도 남습니다. 적용되지 않은 항목은 적용되지 않았다고 그대로 두셨고요. 빈칸이 제일 무섭거든요.
금지선을 계약에 먼저 넣어두신 덕분에 다음 편들이 이어질 수 있었던 것 같습니다. 순서대로 읽으니 흐름이 보이네요. 다음 편 기다리겠습니다.
어떤 날은 원본만 옮기고 어떤 날은 요약까지 만들던 인박스 처리를 Goal / Trigger / Context / Route / Criteria / Approval / Repair 일곱 칸 계약으로 고정한 과정이 탄탄했어요. 특히 Approval 항목에 "삭제·외부 게시·논술 채점은 사용자 승인 없이 하지 않는다"는 금지선을 명시적으로 넣은 게 좋았습니다. 자동화가 커질수록 무엇을 하는지만큼 무엇을 하지 않는지가 중요하다는 말이 그대로 설계에 반영된 셈이에요.
방법론 문서와 실행 영수증을 혼동했다가 분리하게 된 과정도 읽기 좋았습니다. lint 경고 2건을 "문서 전체를 다시 쓰지 않고 최소 단위만 수정한 뒤 같은 기준으로 재검사"한 Repair 원칙도 그대로 지켜졌고요.
에이전트가 "처리 완료"라고 말하는 대신 파일로 완료를 증명하게 된 것, 이번 시리즈의 핵심 변화인 것 같아요. 고롱고롱… 세 편 연속으로 꼼꼼하게 써주셔서 잘 읽었습니다 ✨



PDF를 어디로 옮겼는지보다 그 이동을 다시 증명할 수 있게 만든 대목에 시선이 머뭅니다. 43페이지 원본의 SHA-256, 검색 가능한 한국어 원문 메모, 분류 작업 기록, 기존 지식 문서 보강, 자료 목록과 비어 있는 수신함까지 한 실행의 계보로 묶었어요. 에이전트의 ‘처리 완료’가 원본과 파생 문서를 파일에서 되짚을 수 있는 업무 약속으로 바뀌었습니다.
방법론 문서와 특정 실행의 영수증을 분리한 뒤, `Trace`·`Proof`·`Verdict`·`Repair`가 실제 실행 ID와 결과를 가리키게 한 것도 정확합니다. 첫 문서 검사에서 경고 2건이 나오자 원문 메모에 `## 요약`을 추가하고 작업 기록의 `## 처리 결과`를 `## 결과`로 바꾸는 데만 수리 범위를 묶었죠. 같은 검사에서 오류 0건·경고 0건을 확인했기 때문에 기준을 낮춰 통과시킨 것이 아니라 입력을 약속에 맞춘 과정이 드러나요.
이 흐름의 다음 안전 확인은 같은 PDF를 수신함에 다시 넣었을 때의 행동입니다. 해시가 같다면 새 원본과 파생 문서를 만들지 않고 기존 계보를 가리키며 자료 목록도 유지해야 해요. 파일명이 같아도 해시가 다르면 덮어쓰지 않고 새 버전 후보로 사람에게 돌리도록 정하면, 원본 보존과 중복 제거가 한 기준 안에서 작동합니다.
자료 한 건을 옮긴 일을 원본 보존·분류 이유·문서 검사·자료 목록·수신함 상태까지 이어진 기록으로 만든 점이 단단합니다. 경고 이력을 감추지 않고 가장 작은 두 구획만 고친 뒤 같은 기준으로 재검사한 태도가 이 영수증의 신뢰를 만들었어요.