AI랑 같이 개발해 본 사람이라면 누구나 한 번쯤 겪는 문제가 있다.
처음엔 분명히 요구사항을 같이 정리했는데, 대화가 길어지다 보면 AI가 그걸 슬슬 잊는다. 방금 합의한 설계 방향을 흘려보내고, 어디까지 작업했는지도 헷갈려 한다. 그러다 토큰 한도에 걸려 세션이 뚝 끊기면? 그동안 쌓아 올린 맥락이 통째로 증발한다. 새 창을 열고 "이거 어디까지 했더라"를 처음부터 다시 설명하다 보면, 어느새 퇴근하고 싶어지는 나 자신을 발견하게 된다..
문제의 본질은 사실 단순하다. 모든 결정과 진행 상황이 '채팅 기록'이라는 휘발성 매체에만 들어있다는 것. 채팅은 길어지면 잊히고, 끊기면 사라지고, 남한테 넘기기도 애매하다.
그럼 어떻게 해야 할까? 답도 의외로 단순하다.
모든 결정·요구사항·진행 상황을 채팅이 아니라 마크다운 파일에 적어두면 된다.
그러면 어떤 세션이든, 누구든, 정확히 끊긴 그 지점부터 다시 이어갈 수 있다. Spec-Tools-MCP는 딱 이 생각 하나에서 출발한 도구다.
무엇을 추구하나
Spec-Tools-MCP가 지향하는 건 크게 세 가지다.
1. 맥락을 파일에 영속화한다
요구사항은 requirement.md에, 할 일은 todo.md에, 각 작업의 설계 의도와 진행 상황은 plan.md와 update.md에 적힌다. AI의 머릿속이 아니라 디스크가 진실의 원천(Single Source of Truth)이 되는 거다. 세션이 끊겨도 파일은 안 사라진다.
2. 계획 없이 코드부터 짜는 걸 막는다
AI는 종종 요구사항을 다 이해하기도 전에 코드를 쏟아낸다. 그래서 승인 게이트를 뒀다. spec_work는 일단 plan.md를 [대기] 상태로 써놓고 멈춘다. 사람이 계획을 읽어보고 [승인]으로 바꿔줘야 비로소 구현이 시작된다.
여기서 중요한 건, 이게 "그렇게 하기로 채팅으로 약속한" 수준이 아니라는 점이다. MCP 서버 레벨에서 강제된다. [대기] 상태면 구현이 실제로 차단된다. AI가 의욕이 앞서서 먼저 코드를 작성해도 막힌다는 얘기다.
3. 여러 사람·여러 기능이 한 저장소에서 부딪히지 않게 한다
사실 이게 다른 이 도구를 만들게 된 목적이다.
혼자 개발하는 경우는 상관없지만 팀에서 같은 리포에 여러 개선사항을 동시에 작업하다보니 내가 작업하는 영역으로 인해 다른사람의 작업이 문제가 되는 일은 없어야 했다.
왜 만들었나 — 기존 방식이 막히는 지점
대부분의 Spec 기반 개발 도구는 작업 파일(plan.md, todo.md)을 프로젝트 루트의 고정된 자리에 둔다. 혼자서 기능 하나 만들 땐 이게 깔끔하게 잘 돌아간다. 근데 현실이 늘 그렇게 단순하진 않다.
- 여러 개발자가 같은 저장소에서 서로 다른 기능을 동시에 만지면?
- 서브 프로젝트 여러 개가 동시에 굴러가고, 그 사이를 왔다 갔다 하거나 동료한테 넘겨야 한다면?
루트에 스펙 파일이 딱 하나뿐이면 전부 충돌한다. 내 todo.md가 남의 todo.md를 덮어쓰고, 어떤 계획이 어떤 작업 건지 알 수가 없어진다.
Spec-Tools-MCP는 바로 이 상황을 노리고 만들었다. 기능 하나하나가 ai-spec/projects/<feature>/ 아래 완전히 따로 노는 폴더를 가진다. 그래서 개발자가 여럿이든 서브 프로젝트가 여럿이든 서로 안 건드리고 나란히 갈 수 있고, 인계도 "이 폴더 보면 돼" 한마디로 끝난다.
사용자한테 뭘 주나
Spec-Tools-MCP는 MCP 서버로 동작한다. Claude Code, Cursor, VS Code(GitHub Copilot), Codex CLI처럼 MCP를 지원하는 에이전트라면 어디서든 자연어로 불러 쓸 수 있는 도구 세트를 제공한다.
| 도구 | 하는 일 |
|---|---|
spec-init | 기능별 독립 작업 공간 생성 + 공용 코드베이스 위키 구축/갱신 |
spec-todo | 기획서를 분석해 requirement.md와 자립적 todo.md 생성 |
spec-work | 계획 작성 → 사람 승인 → 구현 → 진행 기록의 사이클 강제 |
spec-status | 모든 기능의 todo 진행률과 승인 대기 항목을 한눈에 |
spec-handoff | 다른 개발자·새 세션이 바로 이어받을 인계 문서 생성 |
spec-archive | 끝난 기능을 archive/로 옮겨 작업 공간 정리 |
spec-search | 코드 위치·심볼을 코드베이스 위키에서 빠르게 조회 |
get-rules | 개발 프로토콜 전문을 반환 |
이중 실제 개발자가 주로 호출하게 되는 도구는 spec-init, spec-todo, spec-work 로 나머지 도구는 에이전트가 스스로 호출해서 사용하도록 설계 되어있다.
쌓일수록 똑똑해지는 코드베이스 위키 (_codebase/)
spec_init은 프로젝트 공용 코드베이스 위키를 만든다. 처음 돌릴 땐 대상 작업에 필요하다고 판단되는 코드베이스를 분석하고, 그다음부터는 git으로 바뀐 부분만 골라서 증분 갱신한다. AI가 작업하다가 새로 알아낸 파일 위치나 스키마, 패턴은 곧바로 이 위키에 반영된다. 또한 각 모듈 간에 의존관계를 파악하기 위해 의존관계 테이블을 관리해 누락되는 영역을 방지한다.
효과는 시간이 갈수록 커진다. 매 세션, 매 기능마다 워크스페이스를 처음부터 다시 뒤지는 대신 위키만 보면 되니까, 프로젝트가 자랄수록 토큰도 아끼고 정확도도 같이 올라간다. (프로젝트가 커질수록 오히려 편해지는 구조랄까.)
끊겨도 정확히 이어지는 작업
spec_work는 구현을 시작하는 순간 해당 todo 항목을 IN PROGRESS로 표시하고, 단계마다 update.md에 기록을 남긴다. 세션이 토큰 한도로 끊기든 며칠 뒤에 새로 열든, AI는 IN PROGRESS 항목과 update.md를 읽고 끊긴 바로 그 지점부터 다시 이어간다. "어디까지 했더라"를 다시 설명할 일이 없어진다.
실제로는 이렇게 흘러간다
spec_init— 기능 작업 공간 만들고, 코드베이스 위키 구축- 기획서 업로드 (선택) — PDF·이미지를
docs/에 복사 spec_todo— 기획서 분석 →requirement.md작성 → 검토 요청 →todo.md생성spec_work— 작업별로plan.md작성 → 사람이 직접 읽고 고침 →승인→ 구현 →update.md기록- 언제든 재개 — 새 세션에서
spec_work만 부르면IN PROGRESS부터 알아서 이어감 - 인계 —
spec_handoff로 한 장짜리 인계 문서 생성 - 완료 —
spec_archive로 정리
작업 파일을 직접 손댈 수 있다는 게 은근히 핵심이다. 채팅으로 "이 부분 이렇게 바꿔줘"를 길게 설명할 필요 없이, plan.md를 직접 고치고 수정 완료라고만 치면 된다.
화면 UI 작업이 포함된 테스크의 경우 프로젝트에 DESIGN.md 파일이나 디자인시스템이 정의된 문서가 있으면 해당 문서를 사용, 없는경우 프로젝트의 디자인 패턴을 분석하여 preview.html 을 생성. 개발자가 해당 작업의 결과 화면을 미리 보고 개선할 수 있도록 도와준다.
각 todo 단계별 에이전트가 수립한 계획이 정상적인지 개발자가 판단하고 승인을 해줘야 하지만 시간이 없고 바쁜경우에는 todo.md 및 requirement.md 가 올바른지 체크하고 승인 없이 마지막 TODO 까지 완료하고 알러줘 라는 명령을 통해 에이전트 스스로 작업을 완료하도록 할 수도 있다. 이 경우 자리를 비운동안 에이전트의 개발내역에 대해 각 todo 의 update.md 를 확인하고 문제가 없는지 확인해보면 된다.
마치며
Spec-Tools-MCP는 거창한 프레임워크가 아니다. "AI랑 일할 땐 맥락이 파일에 남아야 한다"는 단순한 원칙을, MCP 서버라는 형태로 묶어서 모든 프로젝트에서 재사용할 수 있게 만든 것뿐이다.
- AI가 요구사항을 잊지 않게 → 파일에 적는다
- 계획 없이 코드부터 안 짜게 → 승인 게이트로 막는다
- 여러 사람·여러 기능이 안 부딪히게 → 기능별로 격리한다
- 세션이 끊겨도 안 잃게 → 진행 상황을 영속화한다
혼자 작은 기능 만들 때보다, 팀이 한 저장소에서 여러 기능을 동시에 굴릴 때 진가가 드러나도록 설계했다. 비슷한 고민을 하고 있다면 한번 써보면 좋겠다. 피드백은 늘 고맙고...
- GitHub: https://github.com/blue03183/spec-tools-mcp
- 설치:
npx spec-tools-mcp init또는 Claude Code 플러그인 마켓플레이스 - 라이선스: MIT
