컨텍스트 레포·업무 인벤토리·가드레일 훅 구축

안녕하세요, DevOps 챕터에서 일하고 있는 sabo입니다. 계획 편에 이어, 챕터(같은 직무끼리 묶인 팀 단위)의 일하는 방식에 AI를 이식하는 프로젝트의 실제 구축 기록입니다. 이번에 만든 레포는 두 개인데요. 컨텍스트 레포는 팀원 누구나 clone하면 자기 AI가 챕터의 같은 지식을 갖게 되는 곳입니다 — 인프라 문서, 접근 스크립트, AI 공용 스킬, 가드레일 설정이 여기 들어갑니다. 업무 공유 레포는 각자의 작업 디렉토리와 작업 일지가 자동 커밋으로 쌓이는 곳으로, "저 사람 지금 뭐 하고 있어?"를 AI가 읽고 답하게 하는 재료가 됩니다.

이 두 레포의 뼈대가 올라갔고, 업무 인벤토리가 만들어졌고, 가드레일 훅이 배포됐습니다. 그리고 그 과정에서 계획이 세 번 수정됐습니다. 계획 편 말미에 "어디서 어떻게 어긋나는지가 본편"이라고 썼는데, 그 어긋난 지점들이 이 글의 절반입니다.

첫 삽 — AI가 잡아준 아찔한 버그

첫 구현은 AI 에이전트 둘에게 병렬로 맡겼는데요. 하나는 업무 공유 레포에 컨벤션 문서와 시크릿 차단 .gitignore를, 다른 하나는 컨텍스트 레포에 온보딩 원커맨드(install.sh), 자동 커밋 스크립트, 권한 티어 설정 초안을 만들었습니다. 팀원 온보딩이 "clone하고 스크립트 한 번"으로 끝나는 게 목표였고, 뼈대 기준으로는 그렇게 됐습니다.

이 과정에서 에이전트가 진짜 버그를 하나 잡았습니다. 설치 스크립트의 sed 치환이 macOS의 BSD sed에서 에러를 내는데, 그게 set -e와 만나면 사용자의 기존 개인 설정 파일을 통째로 날려버리는 조합이었습니다. awk로 바꿔서 해결했고, 가짜 홈 디렉토리에서 세 번 반복 실행하는 멱등성 검증까지 시켰습니다. 팀원 전원의 로컬에 깔릴 스크립트였다고 생각하면 아찔하죠. AI에게 구현을 맡길 때 "검증 방법까지 지정해서 맡긴다"가 왜 중요한지 몸으로 배웠습니다.

수정 하나 — 머지 게이트 폐기

계획대로 첫 변경사항을 MR로 열었습니다. 정기 미팅에서 협의해 머지한다는 규칙의 첫 적용 대상이었죠. 그런데 열려 있는 MR을 보다가 생각이 바뀌었습니다. 소규모 챕터에서 MR 게이트는 형식이지 안전장치가 아니더라고요. 옆자리에서 "이거 바꿀게요" 한마디면 끝날 일입니다. 그 자리에서 머지하고, 규칙을 "구두 협의 후 main 직접 머지"로 바꿨습니다.

수정 둘 — AI가 두 번 틀린 업무 인벤토리

다음은 업무 인벤토리였습니다. AI를 어디에 먼저 붙일지 고르려면 우리가 무슨 일을 하는지부터 알아야 하니까요. AI에게 사내 위키(Confluence)에 챕터가 쌓아온 데일리·주간보고 페이지 전체를 전수조사시켰습니다.

여기서 재미있는 일이 벌어졌습니다. AI가 두 번 틀렸습니다. 처음엔 "뒤쪽 구간의 기록이 다른 도구로 넘어가 사각지대"라고 결론 내렸고, 재조사에선 "앞쪽 구간은 데일리가 없던 공백"이라고 했습니다. 둘 다 그럴듯했고, 둘 다 틀렸습니다. 주차별 페이지를 배치로 나눠 원문을 전부 다시 뽑게 하자 진실이 나왔죠. 데일리는 전 기간 빠짐없이 있었고, 초기 파싱이 표 형식을 못 잡아 "없음"으로 오판한 거였습니다.

덕분에 최종 인벤토리는 주차 페이지 28장 전수 기준으로 만들어졌고, 그림이 완전히 달라졌습니다. 장애 대응은 기록상 예상보다 훨씬 잦았고, 모니터링 시스템을 바닥부터 구축한 게 가장 큰 프로젝트였다는 것도 이때 제대로 잡혔습니다. AI의 1차 결론은 검증 루프 없이 믿으면 안 됩니다. 같은 AI가 원문 재추출만으로 자기 결론을 두 번 뒤집었으니까요.

인벤토리를 채우다가 계획 하나를 더 접었습니다. 업무별 소요시간을 자기신고로 받아 도입 전 베이스라인으로 삼으려던 것인데, 과거 기록이 없는 상태에서 받는 추정치는 숫자 놀음이더라고요. 측정은 도입 후부터 자동으로 쌓이는 기록(자동 커밋 이력, 장애처리일지)으로 하기로 했습니다.

수정 셋 — 파일럿 하나 폐기

인벤토리에서 "데일리 보고 작성 자동화"가 파일럿(AI를 처음 붙여볼 시범 업무) 후보로 올라왔습니다. 발생 빈도가 가장 높고, 만들어둔 자동 커밋과 딱 맞물린다는 그럴듯한 근거였죠. 승인까지 받아 데일리 초안을 만들어주는 스킬과 스크립트 구현이 끝났는데 — 폐기했습니다. 커밋을 되돌리는 revert 한 번이었습니다.

AI가 파일럿을 정당화하며 "업무 공유 레포는 쓰기만 있고 읽는 곳이 없다"고 했는데, 제가 반문했습니다. 읽는 곳이 없는 게 아니라, 원래 계획에 있던 협업 에이전트("누가 뭘 하고 있어?"에 답하는)가 그 레포를 읽는 거 아니냐고. 맞는 지적이었고, 그렇게 보면 데일리 초안 생성은 이 프로젝트의 필수 요소가 아니라 부가 응용이었습니다.

파일럿은 데이터가 가리키는 것이 아니라 목적에 정합한 것으로 골라야 한다는 걸 여기서 배웠습니다. 데이터상 가장 빈번한 업무가 프로젝트가 풀려는 문제와 같은 건 아니니까요. 그리고 이런 걸 잡아내는 건 여전히 사람의 일이더군요.

가드레일 — 문서를 코드로

마지막은 가드레일 훅이었습니다. "live 서버 변경 전엔 확인", "시크릿 출력 금지" 같은 규칙은 이미 문서에 있었지만, 문서는 읽는 사람에게만 작동합니다. 이걸 실행 시점에 강제하는 훅으로 옮겼습니다.

설계 원칙은 처음엔 "deny는 좁게, ask는 넓게"였습니다. 오탐이 나도 확인 한 번이면 되니까요. 그런데 검토 중에 방향을 하나 더 틀었습니다. rm -rf, kubectl delete, terraform destroy, DROP TABLE 같은 파괴적 명령은 확인(ask)이 아니라 전부 차단(deny)으로. 파괴적 명령은 AI가 실행하지 않는다, 필요하면 사람이 직접 친다 — 이게 우리 챕터의 선입니다. AI가 "삭제해도 될까요?"라고 물어보는 순간 사람은 습관적으로 승인 버튼을 누르게 되거든요. 저부터가 그랬습니다. 아예 물어보지도 못하게 하는 게 맞다고 봤습니다.

구현은 규칙 매트릭스를 설계 문서로 먼저 고정하고, 공식 문서에서 훅 스키마를 검증한 뒤 코딩하게 했습니다. 테스트는 표 기반 47케이스 — 원격 실행 래퍼의 인용부 안에 숨은 명령(우리 챕터의 주 사용 패턴)은 잡아야 하고, grep "rm -rf" doc.md처럼 문자열로만 등장하는 건 흘려보내야 합니다. 전 케이스 통과 후 머지했습니다.

한계도 명문화했습니다. 문자열 검사라 변수 치환으로 우회할 수 있습니다. 이 훅은 샌드박스가 아니라 AI의 실수와 사람의 부주의를 막는 가드레일입니다. 그리고 훅이 판정 불능에 빠지면 차단이 아니라 통과+기록을 택했습니다. 훅 버그가 챕터 전체의 업무를 막는 것보다는 나으니까요.

만든 것과 접은 것

만든 것: 컨텍스트 레포 뼈대, 업무 공유 레포, 업무 인벤토리, 가드레일 훅(테스트 47/47). 접은 것: 머지 게이트, 소요시간 자기신고 베이스라인, 파일럿 하나. 접은 목록이 이렇게 긴데도 아깝지 않은 건, 전부 코드와 문서가 가벼울 때 틀었기 때문입니다.

마치며

다음 작업은 제 로컬에서 훅을 직접 써보며(dogfooding) 오탐을 수집하고, 팀원 온보딩을 거쳐, 업무 현황이 쌓이기 시작하면 협업 질의 스킬(work-status — 업무 공유 레포를 읽고 "누가 뭘 하고 있어?"에 답하는 스킬)을 만드는 것입니다. 다음 편에서 이어가겠습니다.

저희처럼 작은 팀에 AI를 이식하려는 분들께 이 시행착오가 참고가 되길 바랍니다. 긴 글 읽어주셔서 감사합니다.