세밀한 지침이 오히려 사용성을 낮춤
- 문제
- 프로젝트 규칙이 늘면서 기본 컨텍스트가 커지고 실제 작업에 쓸 공간이 줄었습니다.
- 해결
- 서버의 공통 원칙, 도구 선택 설명, 호출 시 필요한 문서의 3계층으로 나눴습니다.
- 결과
- 작업에 필요한 정보를 단계별로 제공하는 구조를 구현했습니다.
개요
개발자마다 AI 도구가 달랐고, 사내 규칙과 문서도 흩어져 있었습니다. CTO님께 개발 AX를 제안하고, 공통 문서·프로젝트 정보·개발자의 검토를 연결하는 MCP 서버를 구축했습니다.
담당 업무
초기 서버 구현 이후 stdio 기반 패키지로 정비. 질문 도구·지침·선행 파일 검사로 개발자의 검토를 지원하고, 작업 기록은 클라이언트 세션과 분리해 보존
- 사용자 환경
- Claude Code·Cursor·Codex 등 동료가 사용하는 도구와 실제 동작을 확인
- 요구사항
- 업무 단계에 맞는 지침 제공, 프로젝트별 보완, 세션을 넘어서는 작업 기록
- 담당 역할
- 사내 적용 제안부터 도구 설계·구현·동작 확인까지 단독 수행
- 플랫폼과 함께 중앙 관리
- 공통 문서
- 중요한 선택은 개발자 확인
- 검토 단계
- 계획·설계·작업 기록 보존
- 산출물
구조
- 01계획요구사항 · 개발자 검토
- 02API·데이터 설계스키마 정의 · 개발자 검토
- 03테스트 작성검증 조건 먼저 정의
- 04구현·검증지침과 선행 산출물 확인
- 05작업 완료SPEC 정리 · 기록 보관
문제 및 해결
충분한 초기 계획만으로 의도가 유지되지 않음
- 문제
- AI가 후속 선택을 맡으면 개발자의 의도와 달라지는 경우가 있었고, 도구별 동작도 달랐습니다.
- 해결
- 직접 동작을 확인하고 질문 도구로 중요한 선택을 개발자가 검토하도록 조정했습니다.
- 결과
- AI의 수행 단계와 사람의 검토 시점을 연결했습니다.
구현 내용
- 3계층 지침
- 서버에 협업 원칙, Tool 설명에 선택 기준, 호출 결과에 현재 단계의 지침과 문서를 담음
- 파일 상태
- 계획·스키마·테스트 등 선행 산출물의 존재를 확인. 대화가 끝나도 기록을 다시 읽을 수 있음
- 문서 재정의
- platform 가이드를 기본으로 custom 문서가 보완. _{toolName} 접두사로 필독 문서를 찾음
- 스키마 검색
- OpenSearch의 API 명세를 검색하며 로컬 MCP에서 내부 검색 서버로 포트포워딩하는 경로를 둠
- 작업 크기
- 정규 흐름은 plan → define_schema → tdd → coding → complete. 작은 수정은 Quick 체크리스트를 제공