커맨드를 치지 않아도 같은 절차를 밟는 AI 하네스

팀의 AI 전환기를 회사 기술블로그에 두 편 썼습니다. 무엇을 만들었는지는 거기 다 적었고요. 이 글은 그 뒤 이야기입니다. 그 파이프라인을 굴리는 하네스를, 분석 커맨드 하나로 시작해 팀과 함께 큰 틀을 짜기까지 어떻게 만들었는지. 핵심은 하나였습니다. 사람이 여럿이라는 것.

회사 블로그에 못다 쓴 이야기

팀의 AI 전환기는 회사 기술블로그에 1편과 2편으로 나눠 썼습니다. 왜 일하는 방식을 다시 짰고, 무엇을 만들었는지. 거기서 다뤘죠.

그래서 여기서 그 얘기를 또 하지는 않겠습니다. 요약본은 원문보다 나을 수가 없거든요.

이 글이 더할 수 있는 건 다른 층입니다. 그 파이프라인을 실제로 굴리는 하네스(AI가 능력을 내도록 감싸는 구조)를 어떻게 설계했나. 정확히는, 어떻게 설계 없이 자라났나.

분석 커맨드 하나에서 시작했다

처음부터 위키를 만들 생각은 없었습니다. 그냥 분석 커맨드 하나였어요.

서비스가 여러 레포에 흩어져 있으니, 문제 하나를 제대로 파헤치려면 여러 레포를 넘나들며 로그와 코드와 데이터를 다 봐야 했는데, 그걸 매번 손으로 뒤지는 게 번거로워서 그 셋을 한 번에 훑는 커맨드를 만든 겁니다. 별거 아니었어요.

분석을 하고 나니 아까웠습니다. 이걸 어디 안 남기나. 처음엔 깃허브 이슈에 적었어요.

그러다 카파시의 llm-wiki를 접했습니다. 매번 원본을 다시 읽지 말고, 한 번 정리해서 서로 링크된 위키로 만들어 두고 그걸 질의하라는 아이디어였죠. 컴파일러가 소스를 미리 한 번 처리해두는 것처럼요.

생각이 바뀌었습니다. 이왕 분석 문서를 만드는 거, AI가 관리하기 좋은 형태로 남기자. 깃허브 이슈보다 프로젝트 위키 문서가 낫겠다.

여기서부터는 되는대로 두지 않았습니다. 이왕 할 거 제대로 하자 싶었거든요. 요청이 들어오면 분석과 설계를 거쳐 구현하고 문서로 남기는, 그 워크플로의 큰 틀을 일부러 그려서 정의했습니다. 그리고 팀원들과 그렇게 일하기로 약속했어요.

큰 틀을 먼저 세우고, 그 안을 채우는 커맨드는 필요할 때마다 하나씩 얹었습니다. 멀티레포라 분석하는 김에 설계도 하고, 설계한 김에 작업 이슈도 뽑고. 그렇게 지금은 스무 개가 넘고, 분석·설계·작업·위키·운영으로 묶여 있습니다.

커맨드 하나는 이렇게 생겼습니다

커맨드는 특별할 게 없습니다. 마크다운 파일 한 장이에요.

앞머리에 이름과 설명을 달고, 본문에 절차를 적습니다. 설명에는 “이런 요청에 이 커맨드를 쓴다”는 트리거 예문을 같이 넣습니다. 사용자가 증상만 던져도 알맞은 커맨드가 잡히도록요. 사용자가 넘긴 말은 $ARGUMENTS 자리에 꽂혀 본문으로 들어갑니다.

운영 이슈를 진단하는 커맨드의 뼈대를 일반화하면 이렇습니다.

---
name: analyze-error
description: >-
  운영 이슈를 로그부터 코드, 데이터까지 한 번에 추적한다.
  이런 요청에 쓴다. 예를 들면 "○○가 안 돼요", "이 에러 왜 나죠?"
argument-hint: "[증상 또는 에러 메시지]"
---

현상: $ARGUMENTS

## Step 0. 과거 이력부터 찾는다 (건너뛰지 않는다)
> 왜: 운영 이슈는 대개 재발한다. 과거 기록을 안 보면
> 이미 끝난 진단을 처음부터 다시 판다.
> 찾은 근거(실행한 검색과 결과)를 먼저 남기지 않으면
> 다음 단계로 가지 않는다.

## Step 1. 로그를 본다
## Step 2. 코드를 추적한다
## Step 3. 데이터를 확인한다

## 출력 형식
0. 관련 과거 이력 (항상 먼저)
1. 진단 요약
2. ...

눈여겨볼 곳은 Step 0입니다. 분석을 시작하기 전에 과거 이력부터 찾게 하고, 찾은 근거를 먼저 출력하지 않으면 다음 단계로 못 가게 막아뒀습니다. 왜 그렇게까지 했는지는 다음 절에서요.

규칙이 는 건 AI를 못 믿어서가 아니다

저 “건너뛰지 않는다” 같은 문구만 보면, AI가 자꾸 거짓말을 해서 조인 것처럼 보입니다. 절반만 맞아요.

진짜 계기는 사람 쪽이었습니다. 저희 회사는 문서가 워낙 빈약해서, 서비스가 어떻게 굴러가는지가 문서가 아니라 몇몇 사람 머릿속에만 담겨 있었거든요. 그래서 팀원들과 규칙을 하나 정했습니다.

모든 작업은 문서로 남긴다.

말은 간단한데, 여러 사람이 각자 AI로 문서를 만들기 시작하니 문제가 생겼습니다. 형식이 제각각인 거죠. 누구는 원인만 적고, 누구는 조치만 적고. 카파시식 위키는 문서끼리 링크로 엮여야 값을 하는데, 포맷이 흔들리면 그 그물이 안 짜입니다.

그래서 규칙이 붙기 시작했습니다. 어떤 필드를 넣을지, 어디에 저장할지, 무엇을 근거로 남길지. Step 0에서 “찾은 근거를 먼저 출력하라”고 한 것도 같은 맥락이에요. 사람이 나중에 그 문서를 믿으려면, AI가 지어낼 수 없는 근거가 문서에 박혀 있어야 하니까요.

결국 규칙은 AI 때문이 아니라 사람 때문에 늘었습니다. 여러 명이 각자 쏟아낸 문서를 한 서가에 모으려면, 형식을 맞추는 규칙이 하나씩 필요했거든요.

통일한 건 도구가 아니라 절차다

그렇다고 전부를 강제하진 않았습니다. 선은 분명했어요.

예를 들어 로그 조회나 DB 확인은 외부 도구 연결이 있어야 되는데, 이건 각자 자율에 맡겼습니다. 설치가 번거롭고, 사람마다 작업 환경 취향도 다르거든요. 그래서 커맨드는 도구가 없으면 그 단계를 건너뛰고, “이 도구가 없어 여기까지만 확인했다”고 명시한 뒤 나머지를 계속합니다. 도구가 있는 사람은 더 깊이 가고, 없는 사람도 막히지 않고요.

그러니까 저희가 맞추려 한 건 도구 자체가 아니었어요. 어떤 절차를 밟고, 그 끝에 무엇이 남느냐였습니다. 무슨 도구를 쓰든 마지막엔 관리 가능한 위키 문서 하나가 나와야 한다는 것. 이 선만 지키니까 사람마다 환경이 제각각이어도 결과물은 같은 서가에 꽂히더라고요.

커맨드를 치지 않아도 같은 절차를 밟는다

여기가 이 글에서 제일 하고 싶은 얘기입니다.

“누가 실행해도 같은 절차”라고 하면, 팀원 전부가 같은 슬래시 커맨드를 외워서 똑같이 친다고 오해하기 쉽습니다. 회사 글에는 “이런 상황엔 이 명령어를 친다”는 식으로 소개했고, 실제로 그렇게 명시해서 부르기도 합니다. 저부터가 그런 편이고요. 그런데 꼭 커맨드를 쳐야만 절차가 도는 건 아닙니다.

커맨드를 스킬로 만들어 뒀기 때문입니다. 스킬은 AI가 알아서 참조하거든요. 그래서 “이 에러 왜 나는지 봐줘”라고 평범하게 말해도, 하네스는 진단 커맨드의 절차를 스스로 불러와 밟습니다. 분석하고, 이슈를 뽑고, 보고서를 쓰고, 위키에 남기는 흐름이 사용자가 명령어를 몰라도 돌아가는 거죠.

그러니까 커맨드를 명시하는 건 취향에 가깝습니다. 쳐도 되고 안 쳐도 되는데, 밟는 절차는 어느 쪽이든 같아요.

이 차이가 큽니다. 표준화가 사람의 규율에 기대면, 누군가 바빠서 절차를 건너뛰는 순간부터 조금씩 새다가 “원래는 이렇게 하기로 했는데” 하는 예외가 쌓이거든요. 그런데 절차를 환경에 박아두면 이야기가 달라집니다. 규율이 아니라 기본값이 되는 거죠. 안 하려고 일부러 애쓰지 않는 한 그냥 그렇게 됩니다.

AI가 판단하게 두지 않은 것

위키가 커지면 문서끼리 어긋나기 시작합니다. 오래돼 사실과 안 맞는 문서, 아무도 안 가리키는 고아 문서, 서로 모순되는 문서. 그래서 위키 상태를 점검하는 커맨드를 뒀습니다.

이 점검 커맨드는 기본이 읽기 전용입니다. 문제를 찾아 보여줄 뿐, 함부로 고치지 않아요. 안전하게 고칠 수 있는 것(끊어진 목록, 빠진 색인 정도)만 별도 플래그를 줬을 때 손댑니다.

나머지는 사람한테 넘겼습니다. AI가 “이 문서는 낡았다”고 짚어도, 그게 의도된 예외일 수도 있고, AI의 오판일 수도 있고, 그냥 지워도 되는 것일 수도 있으니까요. 특히 여러 사람이 AI로 쓴 문서를 한꺼번에 훑는 검사라, AI 혼자 결론까지 내면 틀릴 여지가 큽니다.

그래서 검사 결과를 세션과 함께 날리지 않고 미결 목록으로 남깁니다. 사람이 결정할 때까지요. AI는 초안을 만들고, 판단은 사람이 합니다.

늘리기보다 덜어냈다

하네스를 키우면서 배운 건, 강제를 늘리는 것보다 덜어내는 게 더 어렵다는 겁니다.

점검 커맨드에는 원래 동시 실행을 막는 잠금 장치가 있었습니다. 여러 사람이 같은 시각에 돌리면 서로 충돌할까 봐서요. 그런데 실제로는 그 잠금이 제대로 걸리지도 않으면서 번거로움만 더하는, 있으나 마나 한 장치라는 걸 한참 뒤에야 알았습니다. 그래서 걷어냈어요. 대신 반영을 주간 브랜치 하나로 모으니, 두 사람이 같은 브랜치에 밀어 넣으면 git이 알아서 뒤에 온 쪽을 멈춰 세워 주더군요. 락으로 풀려던 문제가 브랜치 전략으로 사라진 겁니다.

외부 도구도 여럿 붙여보려다 접었습니다. 알림이나 세션 리플레이 같은 걸 연동하려 했는데, 비용이나 연동 실패로 무산된 게 있어요. 부차적인 거라 미련은 없습니다.

지식 검색에 벡터DB를 쓸까 고민한 적은, 솔직히 없습니다. 팀원들이 각자 레포를 클론해서 로컬에서 일하다 보니 grep과 파일 읽기가 자연스러웠고, 문서가 백 건 남짓이라 그걸로 충분했거든요. 애초에 저희가 빌린 카파시의 위키 개념 자체가 “RAG 대신 위키”라서, 벡터를 꺼낼 이유가 급하지 않았던 것도 있고요.

버린 커맨드는 별로 없습니다. 대신 있는 걸 계속 고쳤어요. 큰 틀은 처음에 세웠지만, 그 안은 이렇게 계속 손보면서 지금 모양이 된 겁니다.

아직 열려 있는 것들

아직 매끄럽지 않은 것부터 적겠습니다.

문서 품질은 계속 사람이 봐야 합니다. AI가 만든 위키는 자라는 만큼 낡기도 하니까요. AI의 분석은 어디까지나 초안이라, 중요한 결정은 여전히 사람이 검증합니다.

팀원마다 이 방식에 익숙해진 깊이도 다릅니다. 누구는 커맨드 없이도 술술 쓰고, 누구는 아직 손에 붙지 않았고요. 위키를 사내 다른 팀도 보기 좋게 발행하는 일은 지금도 손보는 중입니다.

그래도 한 가지는 분명해졌습니다. 문서가 “시간 나면 쓰는 것”에서 “일하면 남는 것”으로 바뀌었다는 것. 사람 머릿속에만 있다가 퇴사와 함께 사라지던 맥락이, 이제 서가에 쌓입니다. 거기까지 온 게 이 하네스가 준 가장 큰 값이라고 봅니다.