1분반-심포니

프로젝트 개요

기술개발 과제

국문 : AI 코딩 도구를 위한 MCP 기반의 협업 스키마 개발 및 적용 프레임워크 구축

영문 : Framework for Developing and Applying MCP-based Collaborative Schema for AI Coding Tools

과제 팀명

Symphony 팀

지도교수

이경재 교수님

개발기간

2025년 9월 ~ 2025년 12월 (총 4개월)

구성원 소개

서울시립대학교 컴퓨터과학부 20209200** 박*환

서울시립대학교 컴퓨터과학부 20209200** 박*익

서울시립대학교 컴퓨터과학부 20209200** 배*찬

서울시립대학교 컴퓨터과학부 20209200** 이*관

서론

개발 과제의 개요

개발 과제 요약

◇ 과제명: AI 코딩 도구를 위한 MCP 스키마 개발 및 적용 프레임워크 구축

◇ 핵심 개념: 기존의 정적이고 단편적인 코드 스타일 컨벤션을 넘어, 사용자 역할(RBAC)과 파일의 보안 등급이라는 두 가지 핵심 축을 포함하는 '동적 컨벤션'을 정의한다. 이는 최신 '컨텍스트 엔지니어링 2.0(Context Engineering 2.0)' 논문 연구에 기반하여, 인간의 불명확한 의도(고엔트로피)를 AI가 정확히 실행 가능한 형태(저엔트로피)로 변환하는 체계적인 '엔트로피 감소(Entropy Reduction)' 기술을 구현하는 것이다. 이를 모든 LLM 코딩 툴이 이해하고 적용할 수 있도록 이기종 시스템 간 컨텍스트 공유의 표준인 MCP(Model Context Protocol) 형태로 개발된다. 뿐만 아니라, 이후 컨벤션을 지켰는지에 대한 검수 과정도 자동으로 진행하여 코드 퀄리티를 유지할 수 있다.

◇ 개발 목표: MCP 표준을 통해 개발자 및 비개발자가 자연어 기반의 직관적인 인터페이스로 안전하게 코드 수정에 참여하고, 모든 LLM 코딩 도구가 조직의 고유한 협업 규칙과 보안 정책을 100% 준수하는 코드를 생성하도록 유도한다. 단순한 자동화를 넘어, AI 에이전트가 조직의 맥락을 완벽히 이해하고 협업하는 '컨텍스트 협력(Context-Cooperative)' 시스템을 지향한다. 개발자는 반복적인 검토 및 통합 과정을 자동화하여 생산성을 극대화하며, 직군 간의 사일로를 허물고 공동의 목표를 향해 시너지를 창출하는 차세대 지능형 개발 협업 생태계를 구축하는 것을 목표로 한다.

◇ 기대 효과: GitHub Copilot, Claude Code 등 기존 LLM 코딩 도구를 사용하는 개발 팀이 MCP를 손쉽게 도입하여, 최근 바이브 코딩의 가장 큰 화두인 코드 퀄리티 문제를 해소하고 제품의 시장 출시 기간을 획기적으로 단축시킨다. 특히 AI 에이전트 시대(Era 2.0)에 필수적인 '컨텍스트 격리(Context Isolation)'와 '최소 충분 원칙(Minimal Sufficiency Principle)'을 적용함으로써, AI 도입의 가장 큰 장벽인 보안 우려와 할루시네이션 문제를 기술적으로 해결한다.

개발 과제의 배경 및 효과

◇ 배경

● (만성적인 협업의 비효율성 및 높은 상호작용 비용) 현대 제품 개발은 여러 직군의 협업이 필수적이지만, 현실은 이상과 다르다. 기획자의 워딩 수정, 디자이너의 UI 픽셀 조정 등 간단한 요청조차도 복잡하고 긴 파이프라인(Jira → Slack → 개발 → 배포)을 거치고 있다. 앞의 논문에서 지적하듯, 인간과 기계(시스템) 사이의 '인지적 격차(Cognitive Gap)'로 인해 발생하는 높은 '인간-AI 상호작용 비용'은 조직의 민첩성을 저해하는 가장 큰 요인이다. 이러한 커뮤니케이션 오류와 시간 지연은 단순한 비효율을 넘어 시장 경쟁력을 약화시키고 있다.

● (지능화된 도구의 한계: 맥락 부재와 컨텍스트 오염) GitHub Copilot과 같은 LLM 코딩 도구는 개발 생산성을 향상시켰지만, 근본적으로 '조직의 맥락'을 이해하지 못한다. 범용 데이터로 학습된 모델은 조직 고유의 보안 정책이나 협업 규칙과 같은 '외부 맥락'이 결여되어 있어, 엉뚱하거나 위험한 코드를 생성하는 '컨텍스트 오염'이나 '할루시네이션'을 유발하게 된다. 예를 들어 "결제 코드는 시니어만 수정 가능"과 같은 규칙은 LLM이 알 수 없기 때문에 비개발자의 직접 기여는 예측 불가능한 사이드 이펙트의 위험성 때문에 불가능한 영역으로 남아있다.

◇ 도입 효과

● (개발자 경험의 질적 향상: 사후 대응에서 사전 설계로) 개발자는 더 이상 LLM의 저품질 코드에 대한 반복적인 수정 업무에 시간을 낭비하지 않게 된다. 시스템이 사전에 정의된 컨텍스트 내에서 작동하므로, 에러를 사후에 수정하는 것이 아니라 개발의 첫 단계부터 품질을 관리하는 'Self-Baking(자가 지식화)' 프로세스가 가능해진다. 이를 통해 개발자는 아키텍처 설계 등 고부가가치 핵심 업무에 집중하여 직무 만족도를 높일 수 있다.

● (개발 속도의 혁신적 극대화) 비개발자가 안전이 보장된 범위 내에서 직접 코드 수정에 참여함으로써, 단순 요청 처리 시간을 '수일'에서 '수분' 단위로 압축한다. 이는 논문에서 제시하는 '에이전트 중심 지능(Agent-Centric Intelligence)' 단계의 협업 모델로, 인간의 의도가 즉각적으로 제품에 반영되는 초고속 애자일 스프린트를 가능하게 한다.

● (견고한 코드 품질 및 내장형 보안: 컨텍스트 격리 기술 적용) AI는 MCP에 명시된 동적 컨벤션(코드 스타일, 보안 등급, 접근 제어)을 통해서만 코드를 생성한다. 이는 컨텍스트 엔지니어링의 핵심인 '기능적 컨텍스트 격리(Functional Context Isolation)'를 구현한 것으로, AI가 접근해서는 안 되는 정보나 권한을 원천적으로 차단한다. 이를 통해 인적 실수 및 보안 취약점을 예방하고, 모든 코드 기여가 조직의 표준을 준수하도록 강제한다.

● (쉬운 도입 및 표준화 선점) 몇 단계의 설정만으로 기존 시스템에 통합되어 즉시 사용할 수 있다. 특히 파편화된 AI 도구들을 MCP라는 표준 프로토콜로 연결하는 'Cross-System Context Sharing' 전략은 향후 폭발적으로 증가할 다양한 AI 에이전트들을 단일한 거버넌스 하에 통합 관리할 수 있는 기반이 된다. 이는 단순한 도구 도입을 넘어, 미래형 AI 협업 인프라를 선제적으로 구축하는 효과를 가지게 된다.

개발 과제의 목표 및 내용

◇ 최종 목표: 모든 LLM 코딩 도구에 플러그인 형태로 쉽게 통합 가능한 동적 컨벤션 MCP의 공개 표준을 정의하고, 이를 실제로 적용 및 검증하는 프레임워크를 개발.

◇ 개발 내용

(결과물 1) MCP 컨벤션 서버

● 모든 LLM과 개발 도구가 동적 컨벤션을 일관되게 이해하고 활용할 수 있도록 하는 '범용 컨벤션 양식'를 정의했다.

● (형식)범용성과 가독성을 고려하여 JSON 형식의 표준화된 스키마를 설계한다. 이 파일은 프로젝트의 루트 디렉토리에 .mcp.json 형태로 위치하거나 저희가 제공하는 서버에 저장된다.

- 컨벤션 상세 내용

● 정적 규칙

● ESLint, Prettier 등 기존 린터 및 포맷터 설정 파일(.eslintrc.json, .prettierrc)의 경로를 지정하거나, 핵심 규칙(들여쓰기, 따옴표 종류 등)을 직접 내장하여 일관성을 강제한다.
● 네이밍 컨벤션(component-pascal-case, function-camel-case), 주석 스타일(JSDoc 강제) 등 검증이 가능한 모든 규칙을 포함한다.

● 동적 규칙

● (파일 보안 등급) Glob 패턴을 사용하여 파일 및 디렉토리 경로별로 보안 등급(PUBLIC, INTERNAL, SECRET)을 상세하게 정의했다. 
(예: "src/assets//*": "PUBLIC", "src/components//.css": "PUBLIC", "src/hooks/.js": "INTERNAL", "src/core/payment/**/*.js": "SECRET")
● (역할 기반 접근 제어) 마케터, 기획자, 주니어/시니어 개발자 등 조직의 역할을 정의하고, 각 역할이 파일 보안 등급별로 어떤 권한(read, propose, edit)을 갖는지 명시적인 매트릭스 형태로 명시한다. 이 매트릭스는 누가 어떤 유형의 파일에 대해 아이디어를 제안만 할 수 있는지, 혹은 직접 수정까지 할 수 있는지를 명확히 규정하는 시스템의 핵심이다.

(결과물 2) 동적 컨벤션 검증을 위한 도구를 실제 개발 현장에서 즉시 활용할 수 있도록, 기존 CI/CD 파이프라인에 완벽하게 통합되는 경량화해 제공한다.

● 방식: Plug-and-Play 방식

● 별도의 서버나 복잡한 설정 없이, GitHub 저장소의 .github/workflows 디렉토리 내 워크플로우 파일에 단 몇 줄의 YAML 코드를 추가하는 것만으로 즉시 사용 가능하도록 설계했다.

● 핵심 작동 워크플로우

● (트리거) 개발자 또는 비개발자가 Pull Request(PR)를 생성하거나 업데이트할 때 자동으로 실행된다.
● (컨벤션 로딩) Action이 실행되면, .mcp.json 파일을 찾아와 동적 컨벤션 규칙을 메모리에 로드한다.
● (변경사항 분석) git diff를 통해 해당 PR에서 변경된 파일들의 목록과 내용을 분석합니다.
● (권한 검증) PR 작성자의 GitHub 팀 역할을 기준으로 MCP의 rbac 규칙과 변경된 파일의 security_levels를 대조하여 수정 권한이 있는지 확인한다.
● (정적 규칙 검증) MCP의 static_rules에 따라 린팅 및 포매팅 검사를 수행한다.
● 실시간 피드백 제공
   성공 시: "MCP Convention Check Passed"와 같은 명확한 상태 메시지를 남기고, PR이 병합될 수 있도록 체크를 통과시킨다.
   실패 시: PR 병합을 자동으로 차단하고, 실패 원인을 명확하게 설명하는 코멘트를 PR에 직접 남깁니다. 예를 들어, 권한이 없는 파일을 수정했을 경우, 해당 파일의 해당 라인에 “@작성자,                         
          '마케터' 역할은 INTERNAL 등급의 이 파일을 수정할 수 없다. 개발팀의 검토를 요청해주세요.“ 와 같이 구체적이고 실행 가능한 피드백을 제공하여 개발자의 리뷰 없이도 문제를 즉시 인지하고 
          해결할 수 있도록 돕는다.

구성원/역할: * 이*관 — MCP 정책 파서/규칙 로더, 통합 테스트·시나리오 검증; * 박*환 — MCP 설계 및 핵심 스키마 정의, GitHub Actions 기반 PR 연동/피드백 기능, 통합 테스트·시나리오 검증; * 박*익 — MCP 설계 및 핵심 스키마 정의, GitHub Actions 기반 PR 연동/피드백 기능, 통합 테스트·시나리오 검증; * 배*찬 — 정적 규칙 검증 모듈, GitHub Actions 기반 PR 연동/피드백 기능, 통합 테스트·시나리오 검증

설계

설계사양

제품의 요구사항

본 과제의 목적은 사용자가 자연어 한 줄만으로 팀의 컨벤션을 쉽게 정의할 수 있게 하고, 해당 컨벤션이 바이브 코딩 도구의 작업 과정에서 지속적으로 적용 및 검증되도록 하는 것이다.

사용자는 Agent(MCP 활용), Web dashboard, CLI command를 통해 다양한 방식으로 컨벤션을 정의할 수 있다. 컨벤션은 Git을 통해 소스코드와 함께 버전관리되며, GitHub 사용자는 별도의 추가 절차 없이 팀과 컨벤션을 공유할 수 있다.

바이브 코딩 도구는 MCP를 사용해 작업에 필요한 컨벤션만 선택적으로 가져와 컨텍스트를 최적화한다. 작업 완료 후에는 MCP를 통해 컨벤션 검증을 수행하며, 이 과정은 역할 기반 접근제어(RBAC)와 기존 linter 도구를 결합하여 체계적으로 수행된다. 이를 통해 LLM-as-a-judge 방식 대비 더 빠른 성능과 높은 정확성을 확보한다.

검증 결과는 MCP가 반환하며, 바이브 코딩 도구는 이를 기반으로 컨벤션 위반 사항을 인지하고 교정 작업을 수행하도록 유도한다.

요구사항 목록

번호	요구사항	D/W	비고
1	시스템은 컨벤션을 쉽게 편집하기 위한 편집기를 제공해야 한다.	D	상(컨벤션 편집 및 공유)
2	사용자는 간단하게 한 줄의 자연어로 컨벤션을 편집할 수 있어야 한다.	D	상(컨벤션 편집 및 공유)
3	사용자는 팀원과 컨벤션을 공유할 수 있어야 한다.	D	중(컨벤션 편집 및 공유)
4	사용자의 컨벤션은 반드시 최신 상태를 유지하고 있어야 한다.	W	하(컨벤션 편집 및 공유)
5	사용자는 “파일 I/O는 try/except 사용”과 같은 자연어로 정의된 규칙을 적용할 수 있어야 한다.	D	상(컨벤션 지원 유형)
6	사용자는 작업에 대한 변경사항의 범위를 제한할 수 있어야 한다.	D	상(컨벤션 지원 유형)
7	사용자는 라인 길이, 들여쓰기, 따옴표 등 정적 분석 가능한 규칙을 적용할 수 있어야 한다.	D	상(컨벤션 지원 유형)
8	사용자는 본인이 사용하고 있는 바이브 코딩 툴에 간단히 시스템을 연동할 수 있어야 한다.	D	상(시스템 설치)
9	사용자는 커버리지/복잡도 등 메트릭의 임계값을 설정할 수 있어야 한다.	W	하(시스템 설정)
10	사용자는 시스템을 통해 쉽게 코드에 컨벤션을 강제할 수 있도록 해야 한다.	D	상(컨벤션 적용)
11	바이브 코딩 툴은 컨벤션을 지속적으로 확인할 수 있어야 한다.	D	상(컨벤션 적용)
12	사용자는 시스템의 처리 결과를 확인할 수 있어야 한다.	D	상(컨벤션 적용)
13	사용자는 생성된 코드가 컨벤션에 맞는지 확인할 수 있어야 한다.	D	상(컨벤션 적용)
14	사용자는 생성된 코드를 간단하게 수정할 수 있어야 한다.	D	상(컨벤션 적용)
15	시스템은 요청과 처리 결과에 대한 로그를 기록해야 한다.	W	하(감사 지표)

요구사항 평가

번호	요구사항	평가 방법	평가 기준
1	시스템은 컨벤션을 쉽게 편집하기 위한 편집기를 제공해야 한다.	UI 내에서 컨벤션 편집 기능 접근 가능 여부, 편집/저장 동작을 테스트한다.	편집기 접근 가능, 수정 내용이 정상 저장 및 반영됨
2	사용자는 간단하게 한 줄의 자연어로 컨벤션을 편집할 수 있어야 한다.	자연어로 입력한 규칙(예: “줄 끝에 세미콜론 금지”)이 시스템에 인식되어 반영되는지 테스트한다.	자연어 입력 → 규칙 형태로 변환 및 저장 성공
3	사용자는 팀원과 컨벤션을 공유할 수 있어야 한다.	특정 사용자가 작성한 컨벤션을 팀원 계정에서 접근 및 복제 가능 여부를 테스트한다.	공유 링크 또는 협업 기능으로 팀원이 접근 가능, 팀 권한 관리 정상 작동
4	사용자의 컨벤션은 반드시 최신 상태를 유지하고 있어야 한다.	여러 클라이언트에서 동시에 접근 후 동기화 상태를 확인한다.	변경 사항 발생 시 자동 갱신 또는 수동 새로고침으로 최신 상태 유지됨
5	사용자는 “파일 I/O는 try/except 사용”과 같은 자연어로 정의된 규칙을 적용할 수 있어야 한다.	예시 자연어 규칙 입력 후 코드에 적용 결과를 확인한다.	시스템이 자연어 규칙을 인식하고 코드 분석/검증에 반영함
6	사용자는 작업에 대한 변경사항의 범위를 제한할 수 있어야 한다.	파일 단위의 적용 범위 설정 후 결과를 확인한다.	선택한 범위 내에서만 작업이 수행됨. 위반 시 경고 또는 수정 요청
7	사용자는 라인 길이, 들여쓰기, 따옴표 등 정적 분석 가능한 규칙을 적용할 수 있어야 한다.	정적 분석 규칙을 활성화한 후 코드 검사를 실행한다.	지정된 정적 규칙 위반 시 경고 또는 수정 제안 출력
8	사용자는 본인이 사용하고 있는 바이브 코딩 툴에 간단히 시스템을 연동할 수 있어야 한다.	Claude Code, Codex CLI 등 주요 툴과의 연동을 시험한다.	간단한 설정(예: npm 커맨드 한 줄 입력)만으로 연동 및 기능 동작 확인
9	사용자는 커버리지/복잡도 등 메트릭의 임계값을 설정할 수 있어야 한다.	설정 UI에서 임계값 입력 후 코드 분석을 수행한다.	설정값에 따라 경고 또는 리포트가 정확히 출력됨
10	사용자는 시스템을 통해 쉽게 코드에 컨벤션을 강제할 수 있도록 해야 한다.	매 작업마다 컨벤션 검토 호출 유무를 확인한다.	컨벤션 검토가 모든 작업에서 이루어지는지 검증
11	바이브 코딩 툴은 컨벤션을 지속적으로 확인할 수 있어야 한다.	바이브 코딩 도구가 작업 계획에 따라 적절한 컨벤션을 요청하는지 확인한다.	컨벤션 요청이 모두 성공하는지 확인
12	사용자는 시스템의 처리 결과를 확인할 수 있어야 한다.	코드 분석 또는 컨벤션 검사 후 결과 화면/리포트 표시를 확인한다.	처리 결과(통과/경고/에러 등)가 명확하게 시각화되어 표시됨
13	사용자는 생성된 코드가 컨벤션에 맞는지 확인할 수 있어야 한다.	자동 생성된 코드에 대해 컨벤션 검사를 수행한다.	생성된 코드가 설정된 컨벤션 기준을 충족하거나 위반 시 경고 발생
14	사용자는 생성된 코드를 간단하게 수정할 수 있어야 한다.	코드 생성 후 바로 편집/수정 가능 여부를 확인한다.	생성 코드에 대해 컨벤션 위반 사항을 바로 해결하도록 지시할 수 있는지 검증
15	시스템은 요청과 처리 결과에 대한 로그를 기록해야 한다.	요청 수행 후 로그 파일/DB를 확인한다.	모든 요청과 처리 결과가 시간/사용자 정보와 함께 기록됨

설계 사양

a) CLI Tool: * Language — Go; * CLI Framework — Cobra, survey/v2; * Protocol — Model Context Protocol (go mcp sdk)

b) Web Dashboard: * Framework — Go net/http; * Language — Go, JavaScript; * UI/CSS — Tailwind CSS

c) External Linter Integration: * Linter — ESLint, Prettier, TSC, Pylint, Checkstyle, PMD, golangci-lint

개념설계안 - 컨벤션 구조화 및 CLI 기반 호출 모델

본 설계안은 사용자가 자연어로 정의한 코드 컨벤션을 구조화하고, 바이브 코딩 툴이 CLI를 통해 이를 불러와 검증 및 피드백하는 전체 흐름을 정의한 모델이다. 규칙 정의부터 평가와 피드백까지가 자동으로 순환되는 구조를 갖으며, 자동 피드백 루프를 통해 지속적인 품질 개선이 가능하다.

1. Rule Source (규칙 소스): 사용자가 텍스트 형태로 정의한 컨벤션 규칙이 저장되는 영역이다.; 규칙이 수정·업데이트될 때마다 시스템은 최신 규칙 집합을 반영한다.

2. LLM Agent (자연어 규칙 해석기): LLM 에이전트는 규칙 텍스트를 파싱하고 의미를 분석하여 실행 가능한 코드 규칙 형태로 변환한다.; 이 단계에서 규칙의 의미적 해석과 제약(Constraint) 추출이 수행된다.; 결과적으로 평가 모듈이 이해할 수 있는 ‘명세화된 규칙 코드’를 생성한다.

3. Evaluation (검증 단계): 분석 대상 코드에 필요한 컨벤션 컨텍스트를 수집하고, LLM이 생성한 규칙 코드와 비교하여 평가한다.; 코드 내 위반 여부를 판단하며, 위반 항목이 발견되면 라인 번호, 규칙명 등 세부 사유를 기록한다.; 본 단계는 정적 분석과 의미 분석을 결합하여 수행된다.

4. Feedback (피드백 단계): 규칙 위반이 발견된 경우 위반 사유를 정리하고 수정 방법을 제시하며, 사용자는 수정 후 재검증을 요청할 수 있다.; 위반이 없는 경우 작업 통과로 처리되어 다음 단계로 진행한다.

이론적 계산 및 시뮬레이션

1. LLM Validation Batching & Optimization (LLM 배치 최적화): 목표 — 다수의 의미적 규칙 검증을 배치로 묶어 처리하여 비용과 지연을 최소화한다.; # 동일 파일 및 카테고리별로 작업을 그룹화하여 배치를 구성한다.; # 각 배치마다 컨텍스트 압축을 수행한다(중복 규칙 설명 제거, 변경 라인 ±5줄만 추출).; # Rate limit을 고려하여 병렬 실행으로 동시 처리한다.; # 구조화된 JSON 응답을 파싱하여 개별 규칙 결과로 분해한다.

2. Dependency Engine (레이어드 아키텍처 보호): 목표 — 레이어 간 의존 방향 제약을 강제하여 아키텍처 경계를 보호한다.; 이론적 배경 및 계산; # 모듈 의존 그래프 G=(V,E)를 구축한다 (복잡도: O(|V|+|E|), V=모듈, E=의존 관계).; # 각 모듈에 레이어 번호 ℓ(v)를 할당한다.; # 모든 간선 (u,v) ∈ E에 대해 ℓ(u) ≥ ℓ(v)인 경우를 위반으로 탐지한다(상위 레이어가 하위 레이어에 의존하는 경우).; 레이어 할당은 파일 경로 글롭 패턴 매칭으로 수행한다(예: src/domain/ → L1, src/app/ → L2).; 적용 예로는 클린 아키텍처의 domain ← app ← ui 방향 강제, 마이크로서비스 경계 보호, 보안 모듈 격리 등이 있다.

상세설계 내용

1) 아키텍쳐 설계

패키지 구조 및 의존성

계층 구성요소 설명

Layer	Name	Packages	Responsibility
L0	Bootstrap	cmd/sym	Entry point, provider registration via init()
L1	Commands	internal/cmd	CLI command implementations (Cobra)
L2	Gateways	internal/mcp, internal/server	External interfaces (MCP stdio, HTTP REST)
L3	Core	converter, validator, importer, policy, roles	Business logic
L4	Adapters	internal/linter/, internal/llm/	External tool integration

횡단 관심사 구성요소 설명

Type	Packages	Purpose
Infrastructure	internal/util/git, util/config, util/env	Helper functions, no business logic
Contracts	pkg/schema	Shared data types (DTOs), no behavior

아키텍쳐 다이어그램

LLM Provider 아키텍처 다이어그램

2) 상세 설계

a) 클래스 다이어그램

b) 시퀀스 다이어그램

-Validate 시퀀스 다이어그램-

-Registry Pattern 시퀀스다이어그램-

c) 유즈케이스 다이어그램

3) 인터페이스 설계

a) 사용자 역할별 인터페이스 개요

사용자 역할	주 사용 인터페이스	주요 목적
정책 설정자 (팀 리더, 시니어 개발자)	CLI Command, Vibe Coding Tool(MCP 연동), Web Dashboard	1. 코드 정책(user-policy.json)의 생성·수정·관리 2. 역할 기반 접근 제어(RBAC) 정의
정책 소비자 (모든 개발자)	Vibe Coding Tool(MCP 연동)	AI에게 코드 관련 작업을 요청하고, MCP 정책이 적용된 결과를 텍스트로 확인

b) CLI Command 인터페이스

명령어	서브커맨드	설명	주요 플래그
sym init	-	프로젝트 초기화	--force, --skip-mcp, --skip-llm
sym dashboard	-	웹 대시보드 실행	--port (기본: 8787)
sym my-role	-	현재 역할 확인/변경	--json, --select
sym policy	path	정책 파일 경로 확인/설정	--set
sym policy	validate	정책 파일 유효성 검사	-
sym convert	-	컨벤션 변환	--input, --output-dir
sym validate	-	Git 변경사항 컨벤션 검증	--policy, --staged, --timeout
sym import	-	외부 문서에서 컨벤션 추출	--mode (append/clear)
sym category	list	카테고리 목록 조회	-
sym category	add	카테고리 추가	--file
sym category	edit	카테고리 편집	--name, --description, --file
sym category	remove	카테고리 삭제	--file
sym convention	list	컨벤션 목록 조회	--category, --language
sym convention	add	컨벤션 추가	--category, --languages, --severity, --file
sym convention	edit	컨벤션 편집	--new-id, --say, --severity, --file
sym convention	remove	컨벤션 삭제	--file
sym mcp	-	MCP 서버 시작 (stdio)	--config
sym llm	status	LLM 프로바이더 상태 확인	-
sym llm	test	LLM 연결 테스트	-
sym llm	setup	LLM 설정 안내 표시	-
sym version	-	버전 출력	-
sym completion	-	쉘 자동완성 스크립트 생성	(bash/zsh/fish/powershell)

c) MCP Tool 인터페이스

도구명	설명	입력 파라미터	비고
list_convention	프로젝트 컨벤션 조회	category?, languages?[]	필터링 지원
validate_code	Git 변경사항 검증	role?	RBAC 역할 선택
list_category	카테고리 목록 조회	(없음)	전체 조회
add_category	카테고리 추가	categories[] (name, description)	배치 지원
edit_category	카테고리 편집	edits[] (name, new_name?, description?)	배치 지원
remove_category	카테고리 삭제	names[]	배치 지원
add_convention	컨벤션 추가	conventions[] (id, say, category?, ...)	배치 지원
edit_convention	컨벤션 편집	edits[] (id, new_id?, say?, ...)	배치 지원
remove_convention	컨벤션 삭제	ids[]	배치 지원
import_convention	외부 문서에서 컨벤션 추출	path, mode?	LLM 사용
convert	컨벤션 변환 실행	input_path?, output_dir?	린터 설정 생성

d) Web Dashboard 인터페이스

- user-policy.json 파일을 편집하는 단일 페이지 웹 애플리케이션. 전역 설정과 규칙 관리의 두 영역으로 구성된다.

e) MCP 연동 채팅 인터페이스 상세 설계 (IDE CUI)

- 각 MCP 도구들은 별도의 GUI를 가지지 않으며, 모든 결과는 텍스트 응답의 일부로 출력된다. 사용자는 AI 코딩 도구의 설정에서 "MCP 기능 사용"을 활성화하여, 본 시스템이 제공하는 MCP 도구들을 도구 목록에 추가한다.

f) 인터페이스 연동 및 데이터 흐름도

결과 및 평가

완료 작품의 소개

프로토타입 사진 혹은 작동 장면

- 메인 UI 화면 (dashboard)

- CLI Help 출력

- Claude Code MCP 통합 화면

설치 (Configuration)

a) npm설치

b) sym init

c) MCP 활성화(Cursor)

살행 (Run)

a) CLI 내 sym init 명령어 입력: 프로젝트 내 Symphony 도구 초기화

b) CLI 내 sym dashboard 명령어 입력: 웹 대시보드 열기

c) 웹 대시보드 - 초기 화면

d) 웹 대시보드 - 전역 설정

e) 웹 대시보드 - 템플릿 선택

f) 웹 대시보드 - 컨벤션 가져오기

g) 코드 에디터 내 코드 작성 요청

완료작품의 평가

본 평가는 MCP를 통한 컨벤션 질의·검증 기반 코드 생성 방식과, MCP 미사용 방식(agent.md에 규칙만 주입) 간의 성능 차이를 정량·정성적으로 비교하기 위해 수행되었다.

비교 대상: * Baseline — MCP 미사용 (agent.md 기반 정적 규칙 주입); * Experimental — MCP 사용 (list_convention / validate_code 등)

주요 평가 관점: # MCP 도구 활용도; # Keyword(필수 구현 요소) 충족률; # Retry 이후 성공 여부(자기 수정 능력); # 전체 Task 성공률 개선 효과

평가 데이터: 난이도 높은 코드 컨벤션 15개를 대상으로 하며, 각 컨벤션별로 반드시 포함되어야 하는 키워드(필수 구현 요소)와 포함되면 안 되는 키워드(금지 요소)를 함께 정의하여 평가에 사용하였다.

평가항목	평가방법	적용기준	개발 목표치	비중(%)	평가결과
1. MCP 사용률	MCP tool 호출 로그 분석	list_convention 등 필수 MCP 사용	>90%	20	96.7% (달성)
2. Keyword 충족률	필수 코드 요소 매칭	정책 키워드 누락 없음	>80%	25	88.9% (달성)
3. LLM Validation	Symphony 검증 통과율	내부 검증을 통과하는지 여부	>75%	20	96.0% (달성)
4. Retry 개선 효과	Retry 전/후 violation 비교	Retry 후 통과 여부	80%	20	85.7% (달성)
5. 종합 성능 향상	Baseline 대비 Pass Rate	추출된 목표 키워드 비율	+30%p 이상	15	+46.7%p (달성)

향후계획

a) 어려웠던 내용들

규칙 위치 혼동: MCP를 사용하지 않거나 일부만 사용할 경우, 필요한 규칙을 제대로 참조하지 못해 LLM이 규칙의 출처/적용 대상을 혼동하는 문제가 발생하였다.

실패 원인 파악의 어려움: 최초 실패 시점에서 왜 실패했는지 원인이 명확히 드러나지 않아, 재시도 이후에도 동일한 실수가 반복되는 사례가 있었다.

작업 복잡도 증가에 따른 규칙 누락: 작업 단계가 많아질수록 규칙 누락 가능성이 증가했으며, 다단계 작업에서는 일부 필수 요소가 빠지는 사례가 발생하였다.

LLM 자체 한계(오해/추론 오류): 규칙을 조회했음에도 불구하고 코드에 정확히 반영되지 않는 경우가 존재했으며, 이는 모델의 해석 오류 또는 추론 오류로 인해 발생하였다.

복수 평가 기준 동시 최적화의 난이도: MCP 사용률, 키워드 충족, 재시도 성공률 등 다양한 지표가 동시에 존재하여, 모든 지표를 동시에 개선하는 것이 어렵게 작용하였다.

MCP 효과 설명의 난이도: 결과물이 코드 형태로 나타나기 때문에, MCP가 왜 도움이 되었는지(어떤 과정이 개선되었는지)를 직관적으로 설명하는 데 한계가 있었다.

b) 차후 구현할 내용

컨벤션 규칙 추천 기능: 자주 사용되는 컨벤션 규칙을 사용자에게 추천하여, 중요한 규칙을 놓치지 않도록 사전 확인 단계(추천/체크리스트)를 추가한다.

반복 실패에 대한 대안 제시(상호작용 개선): 단순 재시도에 의존하지 않고, 반복적인 실패 유형을 감지하여 사용자에게 차선(대체 구현, 단계 분해, 제약 완화안 등)을 제시하는 상호작용 기능을 제공한다.

결과 요약 보고서 기능: Pass/Fail, 위반 요약, 재시도 개선 여부 등을 한눈에 확인할 수 있도록 요약 리포트(대시보드/CLI 출력)를 추가한다.

Self-Baking 고도화: Agent의 검증 결과 및 피드백 컨텍스트를 기반으로 Convention Context를 스스로 개선(자가 보강/정제)하도록 기능을 고도화한다.

항목(품명, 규격)	수량	단가	금액	비고
Claude Code (Max)	1	US$220.00	US$220.00	319,332원 (10월 결제)
Claude Code (Max)	1	US$220.00	US$220.00	32,310원 (11월 결제)
ChatGPT (Plus)	1	US$22.00	US$22.00	327,258원 (10월 결제)
합계				678,900원