도입은 도구 선정에서 시작하지 않는다 — 순서·규약·계층 17문답

AI 코딩 에이전트를 팀에 들이려고 하면 질문이 거의 같은 순서로 돌아온다. "무엇부터 하나", "규칙을 어디에 쓰나", "써 놨는데 안 지키면 어떻게 하나" 같은 것들이다. 이 글은 그중 도입과 표준화에 걸린 열일곱 개에 결론부터 답하고 근거를 뒤에 붙인다.

답은 짧다. 각 문항은 판정 기준 한 줄과 그 근거까지만 담고, 구조·설정·실물 예시는 이 카테고리에 이미 나온 글로 넘긴다. 같은 내용을 두 번 읽게 만들지 않는 것이 이 시리즈의 목적이다.

확장 메커니즘(MCP·커맨드·스킬·훅)은 확장 메커니즘 Q&A, 에이전트 설계와 멀티에이전트는 에이전트 설계 Q&A, 운영·권한·비용·장애는 운영과 거버넌스 Q&A로 나눠 두었다.

핵심 판정 기준 정리

도입 구간에서 반복해 등장하는 갈림길들이다. 값이 아니라 무엇으로 가르는가가 요점이다. 아래 분류는 이 글이 열일곱 문항을 배열하며 정리한 것이다.

질문이 깊어지면 어디로 내려가나

Q&A는 진입점이다. 후속 질문이 구조·설정·실물로 내려가는 지점에서 어느 글을 열면 되는지의 지도다. 원 자료가 같은 형태의 안내표를 갖고 있어 그 축을 이 카테고리에 발행본이 있는 범위로 추려 쓰고, 목적지는 이 카테고리의 발행본으로 바꿨다.

Q. AI 에이전트 도입은 어느 순서로 진행하나

업무 선정 → 환경 표준화 → 규약 고정 → 게이트 설치다. 도구 선정은 이 넷 어디에도 들어 있지 않다.

도구를 먼저 정하면 순서가 뒤집힌다. 네 단계는 각각 다른 실패를 막는다.

각 단계의 실물은 합격선 5축과 자동화 대상 선정 · 되돌릴 수 있어야 권한을 넓힌다 · 4계층 Scope · 트리거 주체 축 · Rules·Hooks·Skills 3계층에 나눠 있다.

Q. 첫 자동화 대상은 무엇으로 고르나

2주 안에 회수되는 것부터다.

후보를 감으로 고르지 않으려면 원 자료는 두 도구를 쓴다. 회수 비율을 재는 Idiot Index와, 효과와 구현 공수를 2×2로 놓는 Impact × Effort다.

여기에 하나가 더 붙는다. 입력·출력·판정 기준을 착수 전에 문장으로 고정할 수 있는 일이어야 한다. 그것이 안 되면 "끝났다"를 판정할 수 없어 회수 계산 자체가 성립하지 않는다.

두 도구의 산식과 임계값, 회수에 성공한 일과 실패한 일의 대비 사례, 판정 루브릭은 합격선 5축과 자동화 대상 선정에, 어떤 업무가 실제로 옮겨지는지는 개발조직에 옮길 것에 있다.

Q. 왜 GUI 도구가 아니라 CLI 기반 에이전트인가

루프가 텍스트에서만 닫히기 때문이다.

사람의 의도가 텍스트 명령이 되고, 셸이 해석해 OS가 실행하고, 결과가 다시 텍스트로 돌아오고, 에이전트가 그 텍스트를 읽어 다음 명령을 만든다. 이 순환이 성립하려면 입력만이 아니라 출력도 텍스트여야 한다. GUI는 출력이 픽셀이라 마지막 화살표가 끊긴다. 에이전트 시대에 CLI가 다시 중요해진 것은 취향이 아니라 이 구조 때문이다.

자율성이 세대를 가르는 축이라는 관점은 자율성 3세대에 있다.

Q. 런타임 버전은 무엇을 기준으로 고르나

기본은 LTS이고, 최신 트랙은 필요한 신기능이 지목될 때만이다.

버전 숫자는 몇 달이면 낡는다. 재사용되는 것은 "LTS를 고른다"는 판단 규칙 쪽이다. 버전 관리자도 같은 논리로 시점을 미룬다 — 프로젝트별 버전 충돌이 실제로 생긴 뒤에 도입한다. 단일 프로젝트 단계에서는 과잉이고, 레거시가 여럿 공존하는 조직에서 비로소 의미가 생긴다.

설치·인증 구간의 실물 명령과 버전 표기는 자율성 3세대에 있다.

Q. 프로젝트 컨텍스트는 무엇에 담아 전달하나

매 세션 프롬프트로 반복하지 않고 규약 파일에 상주시킨다.

같은 설명을 매번 다시 쓰면 사람마다 다르게 쓰고, 다르게 쓰면 결과가 갈린다. 원 자료는 규약 파일이 담을 것을 다섯으로 나눈다.

분량은 원 자료 기준 200줄 안팎이 상한이고 실무 권장 목표치는 80~120줄이다. 세부 규칙은 별도 파일로 빼 본문은 색인처럼 남긴다. 계층 구조와 작성 순서는 4계층 Scope, 규약 파일 옆에 서는 나머지 구성물은 .claude/ 여덟 구성물에 있다.

Q. 규칙은 어떤 형태로 써야 에이전트가 판정하나

위반 여부를 기계가 가를 수 있는 형태여야 한다.

사람 대상 컨벤션 문서를 그대로 옮기면 대부분 판정이 안 된다. "깔끔하게"는 어겼는지 확인할 방법이 없고, "커버리지 80% 이상"은 있다. 판정 기준이 있어야 그 규칙에 자동 검증을 걸 수 있고, 검증이 걸려야 규칙이 실제로 지켜진다.

금지를 NEVER 접두사처럼 명시적으로 쓰는 것도 같은 이유다.

원칙의 상세는 되돌릴 수 있어야 권한을 넓힌다, 규칙 문서에서 반복되는 안티패턴은 enforcement 없는 규칙은 위시리스트에 있다.

Q. AI가 고칠 수 있는 코드의 기준은 무엇인가

바꿀 지점을 문자열로 유일하게 특정할 수 있는가다.

부분 수정 도구는 교체 대상 문자열이 파일 안에서 유일해야 동작한다. 특정에 실패하면 에이전트는 파일을 통째로 다시 쓰는 쪽으로 넘어가고, 그때부터 되돌리기가 어려워진다.

그래서 중복 제거와 명확한 네이밍은 미학이 아니라 안전하게 고칠 수 있는가의 문제다. 일치 조건이 정확히 어디까지이고 어떤 코드베이스에서 이 특정이 계속 빗나가는지, 도구별 리스크 등급은 도구 목록이 곧 공격 표면에 있다.

Q. 조직 규모가 커지면 규칙 체계는 어떻게 바뀌나

한 파일 → 모듈화 → 계층 → 관리형 정책으로 단계가 올라간다. 처음부터 마지막 형태로 가지 않는다.

규모 구간별로 어떤 형태를 쓰는지는 .claude/ 여덟 구성물의 규모별 전략 표에, 병합 규칙과 배치 기준은 4계층 Scope와 enforcement 없는 규칙은 위시리스트에, 업종별로 내용이 어떻게 갈리는지는 템플릿 3종 10축 비교에 있다.

Q. 사람마다 결과가 다른 것을 무엇으로 균질화하나

잘 만든 지시를 파일로 저장해 저장소에 올린다.

편차는 개인 역량 문제로 보이지만 실제로는 자산의 소재지 문제다. 좋은 지시가 누군가의 머릿속이나 개인 설정에만 있으면 그 사람이 없을 때 품질이 떨어진다. 그 지시를 커맨드 파일로 저장하고 인자를 받게 만들면 누가 시켜도 같은 절차가 돈다 — 업무 표준 절차서를 파일로 옮기는 것과 같은 일이다.

배포 스코프도 함께 정해야 한다. 개인 설정에만 있으면 팀에 퍼지지 않으므로 프로젝트 단위로 커밋하거나, 조직 차원이면 관리형 경로로 내려보낸다. 에이전트와 규칙을 중앙 저장소에 모으고 서브모듈로 연결하면 프로젝트마다 버전이 갈리는 것을 막을 수 있다.

커맨드·스킬·훅의 파일 구조는 커맨드·스킬·훅과 플러그인 번들, 스코프별 배포는 MCP 도입은 예산 배분이다, 규칙 배치는 enforcement 없는 규칙은 위시리스트, 공유 라이브러리 운영은 잠재 경로는 개수의 제곱으로 는다에 있다.

Q. 반복되는 지적을 어떻게 규칙으로 올리나

리뷰에서 반복해 나오는 지적 서너 개를 규칙 파일로 승격시킨다. 원 자료 기준은 3~5개다.

같은 지적을 사람이 매번 하는 동안에는 그 지식이 리뷰어 개인에게 갇혀 있다. 규칙 파일로 올리는 순간 리뷰 코멘트가 자산이 된다. 반복된 실수는 금지 규칙 형태로 따로 모으고, 훅이 그 파일을 자동으로 만들게 하면 사람이 옮기는 단계도 사라진다.

장애 쪽에서도 같은 경로가 나온다. 원인을 다섯 번 되물어 끝까지 밀면 답이 "이 코드가 틀렸다"에서 "이걸 막는 컨벤션·린트 규칙이 없다" 로 바뀌는 지점이 나온다. 거기까지 가야 재발이 구조적으로 막힌다.

다섯 단을 실제로 끝까지 내려간 사례는 재현 없이 가설 없다, 규칙 파일 모듈화는 enforcement 없는 규칙은 위시리스트, 훅이 강제로 바뀌는 층은 Rules·Hooks·Skills 3계층에 있다.

Q. 규칙을 정해도 지켜지지 않으면 무엇을 하나

enforcement 없는 규칙은 위시리스트다. 문서 규칙과 시스템 강제를 처음부터 분리해 설계한다.

문서는 지시일 뿐이고 지시는 확률적으로 따라진다. 훅은 이벤트만 나면 무조건 실행된다. 이 차이가 "프롬프트로 막는 것"과 "훅으로 막는 것"을 가른다. 그래서 편의는 문서에 두되 보안과 규정은 반드시 강제 계층에 둔다.

강제 계층 안에서도 수단이 갈린다. 패턴으로 표현되는 금지는 권한 설정으로 충분하고, "이 경우에만 막는다" 같은 조건부 규칙은 훅으로 내려간다. 규범·강제·절차 세 층이 각각 무엇을 맡는지는 Rules·Hooks·Skills 3계층, 평가 순서와 설정 계층은 deny가 항상 이긴다, 조직 정책 잠금은 enforcement 없는 규칙은 위시리스트에 있다.

Q. 컨텍스트에 무엇을 상시로 올리나

상시 로드와 조건부 로드를 나눈다. 판정 기준은 "매 세션 필요한가"다.

규약 파일은 세션마다 자동으로 읽히므로 거기 넣은 것은 전부 매번 값을 치른다. 그래서 본문에는 항상 필요한 것만 남기고 세부 규칙은 별도 파일로 빼 필요할 때만 참조하게 한다. 탐색도 같다 — 파일 전문을 읽는 대신 검색으로 위치를 좁히고 그 부분만 읽는다. 붙여 놓고 안 쓰는 도구 서버는 끄는 것이 맞다. 연결만 되어 있어도 정의가 컨텍스트를 점유하기 때문이다.

임계와 회수 방법은 70%에서 끊는 것이 더 빠르다, 도구를 예산으로 다루는 판단은 MCP 도입은 예산 배분이다에 있다.

Q. 긴 작업에서 품질이 떨어지는 것을 어떻게 다루나

앞의 결정이 지워진 것이 아니라 묻힌 것으로 본다. 그래서 조치도 "다시 알려주기"가 아니라 "결정을 파일로 빼기"다.

원 자료가 운영 기준으로 쓰는 값은 컨텍스트 점유율 70%이며, 그 지점을 신호로 체크포인트를 만들고 진행 상태를 파일에 남겨 다음 세션이 이어받게 한다. 대화에만 있는 결정은 세션과 함께 사라진다.

그리고 품질이 나빠졌다는 보고를 받았을 때 모델 회귀부터 의심하지 않는다. 체감의 대부분은 컨텍스트 오염이므로, 새 세션에서 같은 입력으로 재현해 보면 진짜 회귀와 갈린다.

임계·징후·인계 파일의 상세는 70%에서 끊는 것이 더 빠르다에 있다.

Q. 큰 작업은 어떤 절차로 맡기나

임계값을 숫자로 두고 그 위는 계획 승인 없이 구현하지 않는다. 원 자료의 하드 게이트는 3파일 또는 100줄이며, 여기서 100줄은 규칙 문서의 분량이 아니라 한 번에 바꾸는 코드의 줄 수다.

숫자로 두는 이유는 "큰 작업"의 판정을 매번 사람이 하지 않기 위해서다. 임계를 넘으면 절차가 자동으로 바뀐다.

단계로 쪼개는 실익은 되돌리는 비용이 한 단계분으로 제한된다는 데 있다. 한 번에 시키면 잘못됐을 때 전부를 다시 해야 한다.

계획 모드의 실물은 도구 목록이 곧 공격 표면, 업무 분해 패턴은 70%에서 끊는 것이 더 빠르다, 하드 게이트를 규칙 한 줄로 박는 형태는 템플릿 3종 10축 비교에 있다.

Q. 온보딩 문서는 어떤 구조일 때 자가 해결률이 오르나

증상을 나열하는 대신 원인 분류를 먼저 준다.

원 자료가 다루는 환경 문제 20여 건은 사실상 세 갈래로 수렴한다 — 실행 파일이냐, 셸 세션이냐, 인증 주체냐다. 증상은 스무 가지지만 물어볼 것은 세 개다.

증상 스무 개를 목록으로 주면 자기 증상을 찾는 데 실패하지만, 세 분류를 먼저 주면 스스로 좁혀 들어간다. 각 갈래가 어떤 증상으로 나타나고 무엇을 확인하는지를 담은 전체 사전은 되돌릴 수 있어야 권한을 넓힌다에 있다.

Q. 보안팀이 도입을 반대하면 무엇으로 설득하나

감사 가능성과 이중 잠금이다. "안전하다"가 아니라 "무슨 일이 있었는지 남고, 한 겹이 풀려도 다른 겹이 남는다"로 답한다.

감사 가능성 쪽은 도구 호출 전량을 구조화 로그로 남기는 것이다. 도구 실행 직후 걸리는 훅에서 시각·사용자·도구명·작업 디렉터리·입력을 JSON Lines로 누적하면 기존 로그 수집기에 그대로 태울 수 있다.

이중 잠금은 같은 대상을 두 층위에서 막는 것이다. 서버 단위로 비활성화하고, 도구 단위로도 거부 규칙을 건다. 두 층에서 겹쳐 막으면 한 층이 풀려도 다른 층이 남는다.

이중 잠금 원칙의 상세와 권한 평가 순서, 설정 계층은 deny가 항상 이긴다, 조직 단위 정책 잠금은 enforcement 없는 규칙은 위시리스트에 있다.

Q. 벤치마크 점수로 도구를 고를 수 있나

고르는 기준으로는 약하다. 제품이 빠르게 바뀌어 인용한 값이 금방 어긋나기 때문이다.

그래서 점수 자체보다 그 점수가 무엇을 측정한 값인지로 화제를 옮기는 편이 낫다. 원 자료는 수치마다 출처 성격을 붙이고 그 성격을 밝히라는 규칙을 둔다. 성격별로 그 값이 어디까지 유효한지를 아래 오른쪽 열로 붙인 것은 이 글이다.

숫자를 쓰기 전에 어느 칸의 값인지를 먼저 정하는 것이 원칙이다. 이 문항은 판단 규칙 자체가 답이라 내려갈 글을 따로 두지 않았다.

용어 정리

여기까지가 "무엇부터, 어디에 써서, 어떻게 지키게 하나"의 판단이다. 규칙을 파일로 고정하고 나면 다음 질문은 "그 파일들을 무엇이 읽고 실행하나"로 옮겨 간다. MCP·커맨드·스킬·훅이 무엇으로 갈리고 어느 것이 실행을 끊을 수 있는지는 확장 메커니즘 Q&A에서 이어 다룬다.