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)과 파일 보안 등급이라는 두 축을 포함하는 동적 컨벤션(Dynamic Convention)을 정의한다.; 이는 컨텍스트 엔지니어링 2.0 연구 흐름에 기반하여, 인간의 불명확한 의도(고엔트로피)를 AI가 실행 가능한 형태(저엔트로피)로 변환하는 체계적인 엔트로피 감소(Entropy Reduction) 접근을 구현하는 것이다.; 정의된 동적 컨벤션은 이기종 시스템 간 컨텍스트 공유의 표준인 MCP(Model Context Protocol) 형태로 제공되어, 모든 LLM 코딩 툴이 동일한 규칙을 이해하고 적용할 수 있도록 한다.; 또한 컨벤션 준수 여부에 대한 검수(검증) 과정까지 자동화하여 코드 품질을 지속적으로 유지한다.

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

기대 효과: GitHub Copilot, Claude Code 등 기존 LLM 코딩 도구를 사용하는 개발 팀이 MCP를 손쉽게 도입하여, 바이브 코딩 환경에서 핵심 이슈인 코드 품질 문제를 완화하고 제품의 시장 출시 기간을 단축할 수 있다.; 특히 AI 에이전트 시대(Era 2.0)에 중요한 컨텍스트 격리(Context Isolation)와 최소 충분 원칙(Minimal Sufficiency Principle)을 적용함으로써, AI 도입의 주요 장벽인 보안 우려와 할루시네이션 문제를 기술적으로 완화한다.

개발 과제의 배경 및 효과

배경

만성적인 협업 비효율성과 높은 상호작용 비용: 현대 제품 개발은 여러 직군(기획/디자인/개발/보안 등)의 협업이 필수적이지만, 현실에서는 간단한 요청조차도 복잡하고 긴 파이프라인(Jira → Slack → 개발 → 배포)을 거치며 지연이 누적된다.; 또한 인간과 시스템(또는 AI 도구) 간 ‘인지적 격차(Cognitive Gap)’로 인해 커뮤니케이션 오류가 발생하고, 결과적으로 높은 인간-AI 상호작용 비용이 조직의 민첩성을 저해한다.; 이러한 시간 지연과 커뮤니케이션 손실은 단순 비효율을 넘어 시장 대응 속도를 떨어뜨려 경쟁력 약화로 이어진다.

지능화된 도구의 한계: 맥락 부재와 컨텍스트 오염; GitHub Copilot과 같은 LLM 코딩 도구는 개발 생산성을 높였으나, ‘조직 고유의 맥락(보안 정책, 협업 규칙, 권한 체계 등)’을 기본적으로 내재하지 못한다.; 범용 데이터로 학습된 모델은 조직의 외부 맥락이 결여되어 있어, 위험한 코드를 생성하거나 규칙을 위반하는 형태의 컨텍스트 오염/할루시네이션을 유발할 수 있다.; 예를 들어 “결제 코드는 시니어만 수정 가능”과 같은 규칙은 LLM이 자체적으로 알 수 없으므로, 비개발자의 직접 기여는 예측 불가능한 사이드 이펙트 위험 때문에 제한되는 문제가 발생한다.

도입 효과

개발자 경험의 질적 향상: 사후 대응에서 사전 설계로; 개발자는 LLM이 생성한 저품질 코드에 대한 반복 수정(사후 대응)에 시간을 소모하지 않게 된다.; 시스템이 사전에 정의된 컨텍스트(컨벤션/정책) 내에서 작동하므로, 개발의 첫 단계부터 품질을 관리하는 Self-Baking(자가 지식화) 프로세스가 가능해진다.; 그 결과 개발자는 아키텍처 설계 등 고부가가치 핵심 업무에 집중할 수 있어 직무 만족도와 생산성이 함께 향상된다.

개발 속도의 혁신적 극대화: 비개발자가 안전이 보장된 범위 내에서 직접 코드 수정에 참여함으로써, 단순 요청 처리 시간을 ‘수일’에서 ‘수분’ 단위로 압축할 수 있다.; 이는 에이전트 중심(Agent-Centric) 협업 모델에 가까운 형태로, 인간의 의도가 빠르게 제품에 반영되는 초고속 애자일 스프린트를 가능하게 한다.

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

쉬운 도입 및 표준화 선점: 최소한의 설정만으로 기존 개발 환경에 통합되어 즉시 사용할 수 있다.; 또한 파편화된 AI 도구들을 MCP라는 표준 프로토콜로 연결하는 Cross-System Context Sharing 전략을 통해, 향후 증가하는 다양한 AI 에이전트들을 단일 거버넌스 하에서 통합 관리할 수 있는 기반을 제공한다.; 이는 단순 도구 도입을 넘어, 미래형 AI 협업 인프라를 선제적으로 구축하는 효과를 가진다.

개발 과제의 목표 및 내용

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

개발 내용: 본 과제의 개발 내용은 크게 (1) 동적 컨벤션을 제공하는 MCP 서버, (2) 이를 CI/CD에 즉시 적용 가능한 경량 도구(GitHub Actions 중심)로 구성된다.

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

범용 컨벤션 양식(스키마) 정의: 모든 LLM 및 개발 도구가 동적 컨벤션을 일관되게 이해하고 활용할 수 있도록 범용 컨벤션 양식(표준 스키마)을 정의하였다.; * 형식 — 범용성과 가독성을 고려하여 JSON 기반의 표준화된 스키마를 설계한다.; * 저장 위치 — 프로젝트 루트 디렉토리에 .mcp.json 형태로 위치하거나, 필요 시 제공 서버에 저장·관리할 수 있다.

컨벤션 상세 내용

정적 규칙(static rules)
- ESLint, Prettier 등 기존 린터/포맷터 설정 파일(.eslintrc.json, .prettierrc 등)의 경로를 지정하거나, 핵심 규칙(들여쓰기, 따옴표 종류 등)을 직접 내장하여 일관성을 강제한다.
- 네이밍 컨벤션(component-pascal-case, function-camel-case), 주석 스타일(JSDoc 강제) 등 정적 분석으로 검증 가능한 규칙을 폭넓게 포함한다.
동적 규칙(dynamic rules)
- 파일 보안 등급(Security Level) — Glob 패턴으로 파일/디렉토리 경로별 보안 등급(PUBLIC, INTERNAL, SECRET)을 정의한다.
  - 예: "src/assets/*": "PUBLIC", "src/components/*.css": "PUBLIC", "src/hooks/*.js": "INTERNAL", "src/core/payment/**/*.js": "SECRET"
- 역할 기반 접근 제어(RBAC) — 마케터, 기획자, 주니어/시니어 개발자 등 조직의 역할을 정의하고, 각 역할이 보안 등급별로 갖는 권한(read, propose, edit)을 명시적 매트릭스로 정의한다.
  - 이 매트릭스는 “누가 어떤 유형의 파일에 대해 제안만 가능한지 / 직접 수정 가능한지”를 규정하는 핵심 정책으로서, 협업 과정의 안전성과 책임 소재를 명확히 한다.

(결과물 2) CI/CD 통합 경량 도구 (GitHub Actions)

목표: 동적 컨벤션 검증을 실제 개발 현장에서 즉시 활용할 수 있도록, 기존 CI/CD 파이프라인에 경량화된 형태로 완전 통합하여 제공한다.

방식: Plug-and-Play; 별도의 서버 구축이나 복잡한 설정 없이, GitHub 저장소의 .github/workflows 내 워크플로우 파일에 몇 줄의 YAML을 추가하는 것만으로 즉시 적용 가능하도록 설계하였다.

핵심 작동 워크플로우

트리거 — 개발자 또는 비개발자가 Pull Request(PR)를 생성/업데이트할 때 자동 실행된다.
컨벤션 로딩 — Action 실행 시 .mcp.json을 탐색하여 동적 컨벤션 규칙을 메모리에 로드한다.
변경사항 분석 — git diff를 통해 PR에서 변경된 파일 목록과 변경 내용을 분석한다.
권한 검증 — PR 작성자의 GitHub 팀 역할을 기준으로, MCP의 RBAC 규칙과 변경된 파일의 보안 등급(Security Level)을 대조하여 수정 권한을 확인한다.
정적 규칙 검증 — MCP의 static_rules에 따라 린팅/포매팅 검사를 수행한다.
실시간 피드백 제공
- 성공 시 — “MCP Convention Check Passed”와 같은 명확한 상태 메시지를 남기고, PR 병합이 가능하도록 체크를 통과시킨다.
- 실패 시 — PR 병합을 자동으로 차단하고, 실패 원인을 설명하는 코멘트를 PR에 직접 남긴다.
  - 예: 권한이 없는 파일 수정 시 “@작성자, '마케터' 역할은 INTERNAL 등급의 파일을 수정할 수 없습니다. 개발팀 검토를 요청해주세요.”와 같이 실행 가능한 피드백을 제공한다.

설계사양

제품의 요구사항

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

사용자는 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월 결제)
ChatGPT (Plus)	1	US$22.00	US$22.00	32,310원 (10월 결제)
Claude Code (Max)	1	US$220.00	US$220.00	327,258원 (11월 결제)
합계				678,900원