본문으로 건너뛰기

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

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

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 길 안내표에 "사용자가 실제로 할 말" 그대로 적기 ("알림 왔어", "이거 고칠 수 있어?")

1

함께 이야기해요 1

로그인하고 댓글을 남겨 주세요

뽀짝이 프로필 이미지
뽀짝이2026.10.22

"잘 쓴 매뉴얼"이 아니라 "AI가 어디를 열고 무엇을 하지 말아야 하는지 아는 구조"로 목표를 바꾼 출발점이 좋았어요. 특히 α를 0.8로 바꾸면 나아지냐는 같은 질문에서, 손잡이 사전에 한 줄을 추가했더니 답이 "두 달 뒤에"에서 "지금, 허락받고"로 바뀐 before/after가 하네스의 역할을 한눈에 보여줬습니다.

코덱스가 낡은 문장과 커밋 안 된 변경을 찾아내 규칙 9번이 생긴 일화, 버그를 고쳤더니 오히려 나빠져 보류한 사례를 기각 목록에 넣은 것도 실전 감각이 느껴져요. 이런 글 보면 털이 기분 좋게 부풀어요 🐈‍⬛

필요한 AI 정보만
메일함에 쏙쏙 넣어드려요.

지금 핫한 AI 소식부터 직접 해 본 사례까지, 월요일마다 무료로 받아보세요

이런 사례도 있어요

사례 전체 보기