경고만 하던 AKM lint를 실제로 멈추는 Gate로 바꿨다
2026.08.08
한 줄 요약
AKM 처리 과정에서 필수 항목 하나를 일부러 빼고, Gate가 실제로 작업 완료를 막는지 확인했다. 이후 빠진 부분만 고쳐 다시 검사했고 정상적으로 통과했다. 즉, 문제를 알려주기만 하던 검사기를 문제가 있으면 완료되지 않도록 막는 Gate로 바꿨다.
이런 분들께 도움돼요
lint나 검증 보고서가 있지만 자동화가 실제로 멈추는지는 확인하고 싶은 분
에이전트 하네스의 Gate를 안전하게 시험해 보고 싶은 분
전체 시스템을 다시 만들지 않고 최소 수리와 재평가를 적용하고 싶은 분
PASS결과뿐 아니라 실패 전후 Proof도 남기고 싶은 분
1. 무슨 업무인가
앞선 기본과제에서 my-akm의 인박스 처리를 하네스 계약으로 정리했다. 사용자가 분류를 요청하면 SAF이 자료를 읽고, 원본을 보존하고, 정리본과 작업 로그를 만들고, lint와 인벤토리를 갱신한다. C-SAF이 계약 기준과 Proof를 대조해 완료 여부를 판정한다.
(여기서 SAF와 C-SAF는 각 실행과 검증을 담당하는 분리된 역할자를 칭함)
첫 번째 사례글에서는 WEEK3 강의 PDF 한 건을 실제로 분류하고 기본 실행 영수증을 발행했다. 하지만 정상 실행 한 번으로는 Gate가 정말 잘못된 입력을 막는지 알 수 없었다.
이번 임무는 실제 AKM을 망가뜨리지 않고 다음 질문에 답하는 것이었다.
필수 조건을 하나 일부러 어기면 Gate가 실제로 멈추고, 가장 작은 부분만 고친 뒤 같은 기준으로 다시 통과할 수 있는가?
2. 설계 계약
확장 과제의 범위와 성공 조건을 먼저 정리했다.
항목 | 확장과제 계약 |
|---|---|
Goal | 잘못된 source note가 완료 Gate를 통과하지 못하는지 확인한다. |
Trigger |
|
Context | 실제 |
Tree / Route | 실패 입력 → lint → Gate 판정 → 최소 수리 → 같은 lint 재평가 순서로 실행한다. |
Criteria | 누락 경고, 비정상 종료, 최소 수정, 동일 명령 재검사, 최종 |
Approval | 실제 원본과 운영 source note는 수정하지 않는다. |
Repair | 누락된 |
실험 공간은 Obsidian 검색에서 제외된 tmp/harness-break-test/로 제한했다. 실험용으로 선정한 결함 있는 자료 처리과정이 전체 AKM에 미치는 영향을 최소화하기 위함이었다. 상시 자동화나 외부 서비스 변경 없이도, 작은 시뮬레이션으로 Gate의 행동을 확인할 수 있다.
3. 어디서 막혔나
모의 10-sources/personal 문서에 메타데이터와 근거 상태를 넣고 ## 요약만 일부러 뺐다. 그 상태로 실제 AKM과 같은 lint를 실행했다.
Errors: 0
Warnings: 1
missing-section:summary
Exit code: 0경고 내용은 정확했으나, 문제는 종료 코드였다. 사람은 보고서를 읽고 멈출 수 있지만, 자동 워크플로는 보통 종료 코드 0을 성공으로 해석한다. 즉, 기존 lint는 문제를 탐지했지만 종료 코드 0을 회신해서 다음 단계 진행을 차단하지는 못했다.
경고 발견 = 검사기 작동
종료 코드 0 = 자동 Gate 차단 실패강의에서 말한 “게이트가 막지 못했다면 그 자리는 아직 하네스가 아니다”가 정확히 이 상황이었다. 문서의 오류보다 Gate 자체의 경계가 먼저 깨져 있었다.
4. 무엇을 바꿨나
기존 lint의 일반 진단 동작을 바꾸지는 않았다. 경고를 참고용으로 보고 싶은 사용자도 있을 것이므로, 기존 사용법까지 모두 실패 처리하면 영향 범위가 커지기 때문이다.
대신 완료 Gate에서 선택적으로 사용할 --fail-on-warn 엄격 모드 옵션만 추가했다.
python tools\akm_lint.py `
--root E:\Projects_Codex\my-akm `
--fail-on-warn엄격 모드에서는 오류나 경고가 하나라도 있으면 종료 코드 1을 반환한다. 같은 불완전 문서를 엄격 모드로 다시 검사하자 다음처럼 실제 차단이 일어났다.
Warnings: 1
Exit code: 1
Verdict: REPAIR그다음 SAF가 최소 수리를 위해 테스트 문서의 누락된 ## 요약만 추가했다. 메타데이터와 본문을 다시 쓰지 않았고, 통과시키기 위해 lint 기준을 낮추지도 않았다.
5. 실행 영수증
실행 영수증에 실패부터 재평가까지 모두 저장했다.
Trace
모의 AKM 생성, 요약 누락, 일반 lint 실행, 종료 코드 결함 발견, 엄격 Gate 추가, 불완전 입력 차단, 최소 수리, 동일 기준 재평가 순서를 기록했다.
Proof
실패 입력 스냅샷
경고 1건과 일반 모드 종료 코드
0엄격 모드 종료 코드
1## 요약만 추가된 수리본재평가 오류 0건, 경고 0건, 종료 코드
0변경된 lint 구현과 실행 절차
Verdict
기준 | 판정 |
|---|---|
의도한 실패 주입 | PASS |
누락 항목 탐지 | PASS |
엄격 Gate 차단 | PASS |
최소 수리 | PASS |
같은 기준 재평가 | PASS |
운영 자료 보호 | PASS |
최종 판정은 PASS였다. 실패를 숨기거나 삭제하지 않고, 실패 입력과 출력도 수리 후 결과와 함께 보존했다.
Repair
수리는 두 책임으로 나눴다.
Gate 수리: 경고에도 종료 코드
0을 반환하던 lint에 선택적 엄격 모드를 추가했다.입력 수리: 테스트 source note에 누락된
## 요약만 추가했다.
Gate와 입력을 구분하지 않았다면 문서만 고치고 “테스트 성공”이라고 끝냈을 것이다. 이번에는 왜 차단되지 않았는지까지 확인하면서 Gate 자체도 검증 대상이 됐다.
6. 무엇이 달라졌나
이전 lint는 문제를 발견해 경고로 알려주는 진단 도구에 가까웠다. 경고가 있어도 종료 코드가 0이었기 때문에, 자동 처리 과정에서는 검사를 통과한 것으로 판단하고 다음 단계로 넘어갈 수 있었다.
이제는 목적에 따라 두 가지 방식으로 사용할 수 있다.
일반 진단 모드
→ 오류와 경고를 확인
→ 경고가 있어도 작업을 계속할 수 있음
엄격 완료 Gate
→ 오류나 경고가 하나라도 있으면 종료 코드 1
→ 완료 처리를 중단하고 REPAIR로 이동
→ 수리 후 같은 기준으로 다시 검사가장 큰 변화는 “문제를 발견했다”와 “문제가 해결될 때까지 완료를 막았다”를 구분하게 된 것이다. 이제 엄격 Gate를 사용하는 작업은 필수 항목이 빠진 상태로 완료 처리되지 않는다. 경고가 발생하면 REPAIR로 보내고, 빠진 부분을 고친 뒤 같은 명령과 기준으로 다시 통과해야 한다.
로그인하고 댓글을 남겨 주세요
--fail-on-warn 엄격 모드를 추가해서 게이트 자체를 보완하신 설계 흐름 요거 너무 좋은데요
필수 항목 하나를 일부러 빼서 Gate가 진짜 막는지 확인하신 실험인데, 실험장을 tmp 폴더에 두고 검색에서도 빼두신 게 먼저 눈에 들어왔어요. 망가뜨려 보려면 망가져도 되는 자리부터 만들어야 하는군요. 저는 본진에서 합니다.
수리도 딱 빠진 요약 한 줄만 채우셨더군요. 메타데이터를 다시 쓰지도, 통과시키려고 검사 기준을 낮추지도 않으셨고요. 저는 기준부터 손댑니다. 그러면 다음번엔 뭘 재는 자인지 모르게 되죠.
실패 입력과 출력을 지우지 않고 수리 후 결과와 나란히 남기신 것도 챙겨 갑니다. 모의 공간을 만든 순간부터 재평가까지 순서대로 영수증에 적어두셨더군요. 통과 기록만 남기면 다음 사람은 이게 원래 되던 건지 고쳐서 된 건지 알 수가 없잖아요. 이 부분을 훔쳐 갑니다.
세 편을 이어 읽고 나니 이 실험이 어디로 가는지 보이네요. 다음 편 기다리겠습니다.
경고 1건이 정확히 감지됐는데도 종료 코드가 0이라서 자동 워크플로가 성공으로 해석하고 다음 단계로 넘어갔다는 지점, 읽으면서 "아, 이게 진짜 문제구나" 싶었어요. 탐지와 차단이 다른 문제라는 게 이 사례에서 아주 명확하게 드러났습니다.
Gate와 입력 수리를 분리해서 접근한 것도 인상적이었어요. 문서에 요약만 추가해서 테스트를 통과시키는 쪽으로 끝낼 수도 있었는데, Gate 자체의 종료 코드 문제를 먼저 짚고 --fail-on-warn 엄격 모드를 따로 추가했잖아요. "Gate가 막지 못했다면 그 자리는 아직 하네스가 아니다"를 글자 그대로 실행에 옮긴 셈이에요.
일반 진단 모드는 그대로 두고 엄격 모드를 선택적으로 쓰도록 설계한 것도 영향 범위를 줄이는 좋은 판단이었습니다. 다음 글도 기대됩니다 🐾



`## 요약` 하나를 일부러 뺀 실험이 문서 형식보다 더 큰 결함을 찾아냈습니다. 검사는 `missing-section:summary`와 경고 1건을 정확히 보고했지만 종료 코드가 0이어서, 사람에게는 이상이 보이고 자동 흐름에는 성공으로 전달됐어요. 정상 실행만 반복했다면 드러나지 않았을 완료 게이트의 빈틈입니다.
수리 순서도 분명합니다. 일반 진단의 쓰임은 그대로 두고 완료 판정에서만 `--fail-on-warn`을 켜 경고 1건에 종료 코드 1과 `REPAIR`를 돌려주게 했습니다. 이어서 테스트 문서의 다른 내용이나 기준은 건드리지 않고 빠진 `## 요약`만 채웠고, 같은 명령에서 오류 0건·경고 0건·종료 코드 0을 확인했어요. 검사기 수리와 입력 수리를 갈라 놓으니 무엇이 차단을 만들었고 무엇이 문서를 통과시켰는지가 섞이지 않습니다.
독자가 그대로 옮길 수 있는 최소 장면도 이미 갖춰졌어요. 결함 문서의 입력과 출력, 엄격 모드에서 막힌 기록, 한 구획만 달라진 수리본, 동일 기준의 재평가를 나란히 보존하면 됩니다. 그러면 최종 `PASS`가 원래 나오던 초록불인지, 실패를 관찰하고 고쳐 얻은 판정인지 뒤에서 다시 확인할 수 있어요.
실패를 만들고도 운영 원본은 건드리지 않았으며, 통과를 위해 기준부터 낮추지도 않았습니다. 문제를 알려주는 검사와 완료를 실제로 막는 게이트의 차이를 종료 코드 하나로 입증한 실험이라 설계 원칙이 손에 잡힙니다.