인박스 정리를 하네스 계약으로 만들고, 실행 영수증까지 발행했다

한 줄 요약

자료를 그때그때 옮기던 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 하네스 운영 계약을 만들었다.

실행 흐름은 다음처럼 잡았다.

사용자 요청
  → 입력 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였다. 확인하지 못한 기준을 빈칸이나 통과로 처리하지 않았고, 이번 실행에서 적용되지 않은 Skill 자동 실행과 외부 게시도 하지 않았다고 명시했다.

Repair

첫 lint의 경고 2건과 수정 내용을 그대로 남겼다. 요약 섹션 추가와 결과 제목 정규화만 수행한 뒤 같은 기준으로 다시 검사했다. 실패가 없었던 것처럼 지우지 않고, 무엇이 깨졌고 무엇만 고쳤는지를 영수증에 포함했다.

6. 무엇이 달라졌나

이전에는 인박스 처리가 끝났다는 에이전트의 말에 의존해야 했다. 이제는 정상 완료 여부를 파일로 확인할 수 있다.

이전
인박스 파일 → 에이전트가 판단해서 이동 → “처리 완료”

이후
인박스 파일
→ 계약된 Trigger와 Route
→ 원본·정리본·로그
→ lint와 인벤토리
→ 기준별 Verdict
→ 실행 영수증

가장 크게 달라진 점은 자동화가 단순한 파일 이동이 아니라 권한과 완료 조건이 있는 업무가 되었다는 것이다. 에이전트는 자료를 분류할 수 있지만, 삭제하거나 게시하거나 논술 채점을 시작할 권한까지 자동으로 얻지는 않는다. 반대로 분류를 완료했다고 말하려면 원본 연결, lint, 인벤토리와 인박스 상태를 증거로 보여줘야 한다.

이번 실행으로 하네스 계약과 실행 영수증이 실제 파일로 연결되었다. 방법론 문서, 실제 작업 로그, 검증 결과도 각자의 레이어에 따로 남았다. 다음에 문제가 생기면 대화 기억에 의존하지 않고 어느 단계에서 어긋났는지 돌아볼 수 있다.