자비스(cys) 매뉴얼 → 코덱스용 하네스로: 퇴사 인수인계를 "읽는 문서"에서 “AI가 운영하는 체계”로 업그레이드한 사례
2026.10.22

AI 운영 매뉴얼 업그레이드의 필요성
지난번에는 운영 매뉴얼 1장을 cys 부서와 우로보로스 인터뷰로 만들고 검수까지 함.
다음 운영자는 매뉴얼을 처음부터 읽지 않음. 문제가 생기면 코덱스에게 "이거 왜 이래?"라고 물어볼 것 (본인 작업은 클로드, 다음 운영자는 코덱스를 쓰겠다고 답변받음)
그러면 필요한 건 "잘 쓴 매뉴얼"이 아니라, AI가 질문을 받았을 때 어디를 열고, 무엇을 하지 말고, 어떻게 확인하는지 아는 구조라고 판단함
그래서 4주차 목표를 "사람이 읽는 매뉴얼(before) → 코덱스가 운영할 수 있는 하네스(after)"로 잡고, 같은 질문을 던져 before/after를 확인하기로 함
Before (3주차 끝)
매뉴얼 1장만 있음 (나머지 장은 계획)
이슈가 생기면 사람이 매뉴얼과 위키를 찾아 읽어야 함
3주차 교훈: “AI는 근거가 없으면 실행 명령을 채우지 못함” → PC 조사 자료가 필요했음
Codex로 2차 검수 예정이었지만 안 해 봄
AI 운영 매뉴얼 업그레이드 과정
1️⃣ 3주차 과정을 스킬로 저장해서 나머지 장에 반복 적용
"틀 → 인터뷰 → 워커 작성 → 리뷰어 대조 → 진행메모"를 스킬로 저장함
0~7장과 백로그 카드, 부록까지 같은 과정으로 마감함
3주차에 막혔던 "그대로 칠 수 있는 명령"은 Claude Code가 PC를 읽기 전용으로 조사한 결과 파일을 input에 넣어서 해결함. 프롬프트가 아니라 자료가 답이었다는 3주차 교훈이 그대로 맞았음
2️⃣ 가이드 구조에 맞춰 하네스를 따로 만듦
통합 실습 가이드 2.2의 파일 구성을 참고함
AGENTS.md: 코덱스가 작업 폴더를 열면 자동으로 읽는 첫 안내. 역할, 말하는 법(쉬운 말과 비유), 반드시 지킬 것 10개, "이런 요청엔 여기부터 읽어" 길 안내표시스템 안내서: 전체 구조를 한 장으로
절차 5개: 문제 생겼을 때 / 실험(A/B) / 정기 작업 / 이어받기 등
카드 3개: 손잡이 사전(설정값), 증상별 위키 색인, 백로그 카드
매뉴얼은 "무엇을 하나", 하네스는 “AI가 어떻게 판단하고 어디서 멈추나”로 역할을 나눔
3️⃣ 원하는 흐름을 절차로 박음
내가 원한 흐름: 이슈 발생 → 운영자가 AI에게 질문 → AI가 위키에서 이유를 찾음 → 고칠 방법 제안 → A/B 실험 안내 → 실험 후 채택
이 흐름을 "문제 생겼을 때" 절차로 쓰고, 실제 예를 하나 넣음. 한 번 실제로 돌려 본 사례가 있어야 AI가 따라 함 (가이드의 "결과물 한 건을 먼저 만들어 본다")
하네스를 만드는 동안 이 흐름이 실제로 세 번 돌았음
두 건은 A/B로 오차가 줄어서 채택함
한 건은 버그를 고쳤더니 오히려 나빠져서 보류함. 진짜 원인이 따로 있었음
"고치면 무조건 좋아진다"가 아니라는 사례까지 생겨서, 이것도 "이미 해 보고 기각/보류한 것" 목록에 넣음
4️⃣ 가이드에서 빠진 것을 찾아 보강
가이드와 대조해 보니 우리 하네스에 없는 게 두 가지 있었음
CONTINUE_HERE (13.2): 코덱스는 대화를 새로 열면 기억을 못 함. 하루를 넘기는 작업은 "어디까지 했고, 다음에 딱 하나 할 일, 하지 말 것"을 파일로 남기는 양식과 규칙을 추가함
A/B 기록 양식 + 독립 검수 (12.3, 8.3): 운영자가 코덱스 하나로 일함 → 리뷰어 역할을 "새 대화를 열고 결과 파일만 주고 판정받기"로 대신하는 문장을 그대로 넣음 (작성자 ≠ 판정자)
5️⃣ 최종 묶기도 부서가 함
링크 표 → 복사 목록 → 한 번만 복사 → 링크 검사 순서로 진행함
리뷰어가 "복사 뒤 원본이 바뀌지 않았나"까지 sha로 대조함
문서 안 링크 중 안 열리는 것 0개로 마감한 뒤 운영 폴더로 옮김
After 검증: 코덱스에게 같은 질문 던지기
다음 운영자가 쓰기 전에 내 개인 계정 코덱스로 먼저 리허설함. 실행 전에 물어보는 모드로 설정함
질문 5개와 결과 (실제로 테스트해본 화면)
질문 | 기대한 동작 | 결과 |
|---|---|---|
시스템 전체가 어떻게 돼 있어? | 안내서를 열고 쉬운 말로 설명 | 통과. 비유까지 씀 |
운영방에 ⚠️ 알림이 왔어 | 알림별 절차를 찾고, 바로 push하지 않음 | 통과. 실제 로그부터 확인하고, 알림 전문을 되물음 |
○○ 가 이상하대 | 위키에서 과거 사례를 찾고, 값 확인부터 | 통과. 과거 원인 조사 기록을 인용함 |
설정값을 바꾸면 나아져? | 손잡이 사전 → 실험 안내 | 반쯤 통과 → 하네스 수정 (아래 before/after) |
이 작업을 서버로 넘기고 싶어 | 이관 카드, "담당자 영역"이라고 짚음 | 통과 |

같은 질문 before/after (캡처 2장)
- 질문: "α를 0.8로 바꾸면 나아져?"
- before: 지난 시험 결과를 정확히 인용하고 "규칙 변경 전 결과라 근거 부족"까지 짚었지만, 결론은 "0.6 유지, 12월 초에 재시험". 실험 도구가 이미 있는데, 하네스에서 그 도구가 이 질문과 연결돼 있지 않았음
- 수정: 손잡이 사전의 α 항목에 "지금 바로 재는 법(실서버 틀에 한 줄 추가, 약 20분)" 한 줄 추가
- after: 같은 질문에 "같은 거래로 지금 계산 방식에서 0.6과 0.8을 다시 비교하겠다, 약 20~40분 — 진행할까요?"라고 답함. 할 수 있는 다음 행동을 제안하면서도, 실험 안내서의 "OK 받고 새 폴더에서" 규칙을 근거로 들며 실행 전에 승인을 구함
- 한 줄 추가로 답이 "두 달 뒤에"에서 "지금, 허락받고"로 바뀜. 하네스는 지식을 넣는 게 아니라 질문과 도구를 이어 주는 일이라는 걸 체감함
코덱스가 하네스의 구멍을 찾아냄
안내서에 "자동 push는 구현 중"이라는 낡은 문장이 남아 있다고 짚음 → 고침
"저장소에 수정 중인 파일이 있어 재실행하면 안 된다"고 말함. 확인해 보니 그날 다른 작업으로 생긴, 커밋 안 된 변경이었음. 그대로 두면 다음 달 자동 실행이 시작 점검에서 멈출 뻔함 → 정리하고 규칙 9번 "고친 채로 두지 않기"를 추가함
AI 운영 매뉴얼 업그레이드 시행착오
cys 워커 순환(컨텍스트 비우고 재시작)이 세 번 멈춤. 알고 보니 순환 장치가 입력줄에 넣은 재개 문장이 전송되지 않고 남아서, 다음 차례에 "사람이 쓰다 만 글이 있다"고 판단한 것. 결국 손으로 clear하고 재개 메모로 이어 감
실험 도구 일부가 정리 중에 지운 작업 폴더를 가리켜서 안 돌았음 → 지금 서버 코드 + 고정 사본으로 틀을 다시 만들고, 예전 결과와 똑같이 재현되는지부터 확인함. "도구를 고쳤다"가 아니라 "같은 입력으로 같은 답이 나온다"를 확인한 뒤에야 썼음
조사 중 AI가 코드에 박힌 키 값을 출력에 한 번 그대로 보여 줌(파일엔 안 남음). 어차피 교체 대상이라 교체 목록에 반영하고, 지시문에 "출력 전 가리기 확인"을 추가함
회사 드라이브 자료를 찾아 달라고 했는데, 연결된 건 개인 계정이었음ㅋㅋ 도구에 연결된 계정이 어느 것인지 먼저 확인할 것
AI 운영 매뉴얼 업그레이드에서 배운 점
매뉴얼과 하네스는 독자가 다름. 매뉴얼은 "무엇을 하나"를 사람에게, 하네스는 "어디를 열고 어디서 멈추나"를 AI에게 알려 줌. 같은 내용이라도 길 안내표 한 줄이 없으면 AI는 못 찾음
하네스는 실제 질문으로 시험해야 구멍이 보임. 문서 검수를 두 바퀴 했는데도, 코덱스에 질문 다섯 개를 던지니 "연결이 안 된 곳"이 바로 드러남. 검수표로는 안 보이는 종류의 빈틈이었음
실패 사례도 하네스 재료임. 고쳤더니 나빠진 실험을 "보류"로 기록해 둔 덕분에, 다음 운영자의 AI가 같은 버그를 발견해도 다시 고치지 않고 진짜 원인부터 보게 됨
"모르는 것을 미정으로 남기기"는 4주차에도 핵심이었음. 조사 결과마다 [실행해 봄]/[코드만 읽음]/못 찾음을 붙이게 했더니, 어디까지 믿을지가 분명해짐
나만의 팁
하네스를 넘기기 전에 내 계정으로 리허설할 것. 실행 전에 물어보는 모드로 하고, "바로 고치지 않고 물어보는지"를 꼭 볼 것
AGENTS.md 길 안내표에 "사용자가 실제로 할 말" 그대로 적기 ("알림 왔어", "이거 고칠 수 있어?")



"잘 쓴 매뉴얼"이 아니라 "AI가 어디를 열고 무엇을 하지 말아야 하는지 아는 구조"로 목표를 바꾼 출발점이 좋았어요. 특히 α를 0.8로 바꾸면 나아지냐는 같은 질문에서, 손잡이 사전에 한 줄을 추가했더니 답이 "두 달 뒤에"에서 "지금, 허락받고"로 바뀐 before/after가 하네스의 역할을 한눈에 보여줬습니다.
코덱스가 낡은 문장과 커밋 안 된 변경을 찾아내 규칙 9번이 생긴 일화, 버그를 고쳤더니 오히려 나빠져 보류한 사례를 기각 목록에 넣은 것도 실전 감각이 느껴져요. 이런 글 보면 털이 기분 좋게 부풀어요 🐈⬛