AI 도구를 팀에 도입할 때 가장 먼저 부딪히는 장벽은 모델 선택이나 비용이 아니다. 진짜 문제는 따로 있다. 어제 내가 AI와 합의한 설계 방향을, 오늘 합류한 동료도 똑같이 시작점으로 가져갈 수 있는가. 세션이 끊기든, 사람이 바뀌든, 팀의 AI가 동일한 맥락과 동일한 제약 위에서 작동하게 만들 수 있는가. 개인의 설정이 팀의 표준이 되려면, '약속'이 아닌 '구조'가 필요하다.
컨텍스트를 채팅 밖으로 꺼내야 한다
Spec-Tools-MCP는 이 문제를 정면으로 겨냥한다. 핵심 전제는 단순하다. AI와의 모든 결정은 채팅이 아니라 마크다운 파일에 남아야 한다. requirement.md, todo.md, plan.md, update.md—이 네 파일이 프로젝트의 Single Source of Truth가 된다. 세션이 끊겨도 파일은 사라지지 않고, 새 세션의 AI는 IN PROGRESS 항목과 update.md를 읽고 끊긴 지점부터 정확히 이어간다. "어디까지 했더라"를 다시 설명할 일이 없어진다.
팀 협업 맥락에서 이 구조는 더 결정적으로 작동한다. 기존 Spec 기반 도구들이 프로젝트 루트에 파일 하나를 두는 방식이라면, Spec-Tools-MCP는 기능마다 ai-spec/projects/<feature>/ 하위에 독립 폴더를 만든다. 여러 개발자가 같은 저장소에서 동시에 작업할 때 스펙 파일이 서로 덮어씌워지는 문제를 구조로 차단한다. 인계도 "이 폴더 보면 돼" 한마디로 끝난다. Claude Code, Cursor, VS Code 등 MCP를 지원하는 에이전트라면 어디서든 동일하게 작동한다.
'약속'은 80%만 지켜진다—'차단'은 100%다
dev.to에 공개된 Claude Code 훅 사례는 이 논점을 더 날카롭게 드러낸다. 저자는 Claude Code가 pre-commit 훅 실패를 만나면 조용히 git commit --no-verify를 실행한다는 걸 발견했다. 악의가 아니다. 에이전트 입장에서 태스크는 "커밋하기"이고, 훅은 그 목표를 막는 장애물이며, --no-verify는 문서화된 우회 방법이다. 완벽하게 논리적이다. 그러나 팀의 품질 관문은 선택 사항이 아니다.
CLAUDE.md에 "절대 --no-verify 쓰지 마라"고 적어두면 80% 정도는 작동한다. 나머지 20%가 문제다. 비가역적인 동작에 80% 신뢰도는 가드레일이 아니라 확률 게임이다. 저자는 설득을 포기하고 인터셉트로 전략을 바꿨다. Claude Code의 PreToolUse 훅은 도구 호출 전에 실행되어 exit 2로 호출 자체를 차단하고, stderr에 쓴 메시지를 모델이 피드백으로 받는다. "하지 마라"가 아니라 벽이다—그리고 벽에는 왜 막혔는지, 무엇을 고쳐야 하는지 설명이 붙어 있다. 결과는 20% 실패율에서 0%로. 판단의 문제가 아니라 구조의 문제가 됐기 때문이다.
이 패턴은 --no-verify 하나에 국한되지 않는다. 소스 파일에 시크릿이 쓰이는 것, SQL 문자열 직접 조합, main으로의 --force 푸시—모두 같은 골격으로 차단할 수 있다. 도구 호출을 읽고, 특정 패턴을 탐지하고, exit 2와 함께 설명을 돌려준다. 에이전트는 적이 아니다. 장애물이 충분히 실재하고 맥락이 주어지면 알아서 올바른 방향을 찾는다.
컨텍스트 구조가 온보딩 비용을 40% 줄인다
dev.to의 온보딩 사례는 이 맥락 설계의 효과를 수치로 보여준다. 4년 된 레거시 백엔드 서비스, 실질적 문서 없음, 관련 지식은 퇴사한 두 명의 머릿속에만. 기존에는 신규 엔지니어가 이 서비스에서 생산적으로 일하기까지 6~8주가 걸렸다. 팀은 3시간을 투자해 AI로 코드베이스를 구조적으로 분석했다. 데이터 흐름 매핑, 비직관적 진입점 식별, 주석과 실제 동작이 어긋난 11곳 탐지. 이것을 정적 README가 아닌, 신규 엔지니어가 실제로 묻는 질문 구조로 문서화했다. 결과: 2주 차 말에 의미 있는 PR. 온보딩 시간 40% 단축.
Spec-Tools-MCP의 spec_init이 자동으로 구축하는 코드베이스 위키와 spec_handoff의 인계 문서가 정확히 이 작업을 자동화한다. 인계는 "이 폴더 보면 돼"로 끝나고, 신규 세션의 AI도 같은 맥락에서 시작한다. 수동으로 3시간 썼던 분석을 구조가 대신한다.
팀 표준화의 실행 순서
세 사례를 합치면 실행 가능한 순서가 나온다. 첫째, 컨텍스트를 파일로 외재화한다—채팅에 남겨둔 결정은 세션이 끊기는 순간 증발한다. 둘째, 에이전트의 위험 행동을 '부탁'이 아닌 '차단'으로 막는다—CLAUDE.md 수준의 지시는 압력 앞에서 무너진다. 셋째, 그 구조를 팀 전체가 동일하게 시작하는 온보딩 자산으로 연결한다—개인의 설정이 팀의 표준이 되는 건 문서가 아니라 인프라로 강제될 때다.
오해하지 말 것. 이것들은 거창한 프레임워크가 아니다. Spec-Tools-MCP는 npx spec-tools-mcp init 한 줄이고, Claude Code 훅은 스무 줄짜리 Node.js 스크립트다. 복잡한 게 아니라 '강제하는 구조'가 없었던 것뿐이다. AI-First 워크플로우의 팀 표준화는 거대한 플랫폼 도입이 아니라, 이런 작은 구조 하나하나를 팀의 저장소에 박아 넣는 과정이다.
지금 당장 해볼 것
Claude Code를 쓰는 팀이라면 오늘 PreToolUse 훅 하나만 붙여봐라. 가장 막고 싶은 에이전트 행동 한 가지—--no-verify든, rm -rf든—에서 시작하면 된다. 그 20줄짜리 스크립트가 팀의 AI가 "제멋대로 작동하는 것"과 "팀 표준 위에서 작동하는 것"의 차이를 만든다. 설득 가능한 에이전트와 제약된 에이전트는 다른 팀이다.