연동 워크플로

배울 내용

커스텀 서브에이전트, 규칙, MCP 서버를 결합해 실제 개발 시나리오에 적용하는 실용적인 연동 워크플로입니다.

연동 방법

방법	가장 적합한 경우	설정
커스텀 서브에이전트	AI 기반 전문 작업	`~/.verdent/subagents/*.md`
규칙(AGENTS.md)	팀 표준과 동작 방식	프로젝트 루트의 `AGENTS.md`
MCP 서버	프로토콜을 준수하는 외부 도구	`.mcp.json`(프로젝트 루트)

철학: 여러 방법을 조합해 필요에 맞는 종합적인 워크플로를 만듭니다.

일반적인 연동 패턴

데이터베이스 개발 워크플로

스택: 마이그레이션 리뷰어 서브에이전트 + AGENTS.md 표준 + PostgreSQL MCP 서버

서브에이전트:

---
name: migration-reviewer
description: Reviews database migrations for safety
---
Checks: Destructive operations, reversibility, indexing, blocking operations

AGENTS.md:

## Database Standards
- All migrations reviewed by @migration-reviewer
- Test on staging before production
- Include rollback procedures

MCP: 쿼리 실행, 스키마 검사, 마이그레이션 검증을 위한 PostgreSQL 서버

워크플로: 마이그레이션 작성 → @migration-reviewer가 검증 → MCP이 스테이징에서 테스트 → PR 문서화

보안을 포함한 API 개발

스택: 보안 감사자 + AGENTS.md 규칙 + 커스텀 API 테스트 도구

구성 요소:

서브에이전트: @api-security-auditor - 입력 검증, SQL 인젝션, 인증, 속도 제한
규칙: 모든 엔드포인트는 보안 리뷰가 필요하며, 공개 API에는 속도 제한을 적용합니다.
외부 도구: 커스텀 연동을 통한 자동 엔드포인트 테스트와 보안 스캔

결과: PR 승인 전에 자동 보안 리뷰가 수행됩니다.

API 테스트 및 보안 스캔 도구는 도구 구성에 따라 커스텀 MCP 서버 구현이나 다른 연동 방법을 통해 연동할 수 있습니다.

프론트엔드 접근성

스택: 접근성 감사자 + WCAG 규칙 + Lighthouse 연동

워크플로:

Create component → @a11y-auditor reviews → Lighthouse tests accessibility → Rules enforce >90 score

Lighthouse와 기타 접근성 도구는 워크플로에 따라 커스텀 MCP 서버 또는 CI/CD 파이프라인 연동을 통해 연결할 수 있습니다.

MCP 설정 예시

MCP 이해하기

**Model Context Protocol(MCP)**은 애플리케이션이 LLM에 컨텍스트를 제공하는 방식을 표준화하는 오픈 프로토콜입니다. MCP 서버는 이 프로토콜을 구현하는 실행 파일입니다. 데이터베이스 연결이나 API 엔드포인트가 아니라, 실행되어 JSON-RPC 2.0으로 통신하는 프로그램입니다.

핵심 개념:

MCP 서버: MCP 프로토콜을 구현하는 실행 파일(Node.js 패키지, Python 스크립트 등)
설정: Verdent이 서버를 시작하는 방법을 알려줍니다(command + args).
통신: 서버는 자체 비즈니스 로직(쿼리, API 호출 등)을 처리합니다.

기본 설정

위치: 프로젝트 루트의 .mcp.json

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://localhost:5432/myapp_dev"
      ]
    }
  }
}

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-github"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://localhost:5432/myapp_dev"
      ]
    },
    "github": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-github"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

설명:

mcpServers - MCP 설정에 필요한 최상위 키
command - 실행할 실행 파일(일반적으로 Node.js 패키지에는 npx 사용)
args - 명령에 전달되는 인수(패키지 이름, 연결 문자열 등)
env - 인증/설정을 위한 환경 변수

다중 환경

{
  "mcpServers": {
    "postgres-dev": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "${DEV_DATABASE_URL}"
      ]
    },
    "postgres-staging": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "${STAGING_DATABASE_URL}"
      ]
    },
    "postgres-prod": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "${PROD_DATABASE_URL}"
      ]
    }
  }
}

권장 사항: 자격 증명을 안전하게 유지하려면 연결 문자열에 환경 변수를 사용합니다. MCP 서버는 구현 방식에 따라 내부적으로 읽기 전용 동작을 처리합니다. 접근 제어 옵션은 해당 서버 문서를 확인하세요.

MCP 더 알아보기:

Model Context Protocol 사양
MCP 서버 레지스트리 - 사용 가능한 MCP 서버 둘러보기
공식 MCP 서버 - PostgreSQL, GitHub, Filesystem 등

워크스페이스 연동

프로젝트별 설정

설정:

프로젝트 루트에 저장합니다: .mcp.json
팀 공유를 위해 버전 관리에 커밋합니다.
팀원은 프로젝트 MCP 서버를 자동으로 사용합니다.

마이크로서비스 예시:

{
  "mcpServers": {
    "users-db": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://localhost:5432/users"
      ]
    },
    "orders-db": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://localhost:5433/orders"
      ]
    }
  }
}

Kafka 같은 추가 서비스에는 호환되는 MCP 서버 구현이 필요합니다. mcp.so/servers의 공식 MCP 서버 레지스트리에서 사용 가능한 커뮤니티 서버를 확인할 수 있습니다.

팀 협업

공유 AGENTS.md 표준

팀 전체의 일관성을 위해 버전 관리에 커밋합니다.

# AGENTS.md

## Code Review Process
- Run @code-reviewer before PR
- Address all security warnings
- Minimum 80% test coverage

## Integration Requirements
- @migration-reviewer for database changes
- @api-security-auditor for new endpoints
- @a11y-auditor for UI components

## MCP Servers
- Use postgres-staging MCP server for queries
- Never use postgres-prod MCP server for exploratory queries

장점: 일관된 동작, 표준 적용, 자동 품질 게이트.

멀티 에이전트 조정

복잡한 기능 워크플로

예시: 새 결제 엔드포인트

1. Developer request → 2. Main agent generates code →
3. @api-security-auditor reviews security →
4. @migration-reviewer validates schema →
5. MCP tests on staging →
6. Main agent generates tests and PR

결과: 보안 및 데이터베이스 권장 사항이 적용된, 완전히 리뷰된 엔드포인트입니다.

연동 권장 사항

단계적 도입

1단계: 기본 규칙

## Code Standards
- Use TypeScript strict mode
- Run tests before commit

2단계: 전문 서브에이전트 추가

## Code Review
- Run @security-reviewer before PR

3단계: MCP 연동

## Database Access
- Use MCP postgres-staging for queries

전략적 조합

조합	목적	예시
규칙 + 서브에이전트	규칙은 언제를 정의하고, 서브에이전트는 분석합니다	AGENTS.md: "Review with @security-reviewer"
규칙 + MCP	규칙은 어떤 서버를 지정하고, MCP는 접근합니다	AGENTS.md: "Use db-staging only"
서브에이전트 + MCP	서브에이전트가 외부 데이터에 MCP를 사용합니다	보안 감사자가 API 엔드포인트를 쿼리합니다

팀 문서화 권장 사항

팀을 위해 연동을 문서화할 때는 다음을 포함합니다.

커스텀 서브에이전트: 각 서브에이전트의 이름, 목적, 호출해야 하는 시점을 나열합니다.
AGENTS.md 규칙: 각 표준의 “왜”를 설명하는 근거와 함께 규칙을 문서화합니다.
MCP 서버: 각 서버의 목적, 접근 수준(읽기 전용/쓰기), 사용 시점을 설명합니다.
연동 워크플로: 구성 요소가 함께 작동하는 방식을 보여주는 예시 워크플로를 제공합니다.
문제 해결: 현재 설정에 특화된 일반적인 문제와 해결 방법을 문서화합니다.

새 팀원이 설정을 빠르게 이해할 수 있도록 연동 문서를 .mcp.json 및 AGENTS.md 파일과 함께 커밋하세요.

문제 해결

문제: 예상한 시점에 서브에이전트가 호출되지 않음

확인:

위치: 파일이 ~/.verdent/subagents/[name].md에 있는지 확인합니다.

YAML 프런트매터: 필수 name 및 description 필드를 포함한 유효한 문법인지 확인합니다.

호출 정책: 사용 방식과 일치하는지 확인합니다(strict는 명시적인 @-mention이 필요함).

설명: 에이전트 description가 서브에이전트를 사용해야 하는 시점을 정확히 설명하는지 확인합니다.

재시작: 서브에이전트 정의를 다시 로드하려면 Verdent을 다시 시작해 봅니다.

일반적인 원인:

서브에이전트 파일 이름 또는 @-mention의 오타
프런트매터의 잘못된 YAML 문법
서브에이전트 description가 작업 컨텍스트와 일치하지 않음

문제: AGENTS.md 규칙이 적용되지 않음

확인:

위치: 파일이 프로젝트 루트 디렉터리에 있는지 확인합니다.

문법: 파싱 오류가 없는 유효한 Markdown인지 확인합니다.

지시 방식: 구체적인 명령을 사용합니다("Try to..."가 아니라 "Always use...").

세션: 새 대화를 시작해 규칙 적용을 새로 테스트합니다.

충돌: 사용자 규칙이 프로젝트 규칙을 의도치 않게 재정의하는지 확인합니다.

일반적인 원인:

AGENTS.md가 잘못된 디렉터리에 있음(프로젝트 루트여야 함)
AI가 다르게 해석할 수 있는 모호한 지시
규칙은 적용되었지만 결과가 예상과 다름(문구를 다듬으세요)

문제: MCP 서버가 시작되거나 연결되지 않음

확인:

문법: .mcp.json에 유효한 JSON이 들어 있는지 확인합니다(검증에는 jq 사용).

구조: 필수 mcpServers 키가 최상위에 있는지 확인합니다.

서버 설정: 각 서버에 command 및 args가 올바르게 지정되어 있는지 확인합니다.

패키지: MCP 서버 패키지에 접근할 수 있는지 확인합니다(npx는 패키지를 자동으로 다운로드하며, -y 플래그는 확인 프롬프트를 건너뜁니다).

환경: env 객체의 변수가 셸에 올바르게 설정되어 있는지 확인합니다.

권한: 서버 실행 파일에 적절한 실행 권한이 있는지 확인합니다.

일반적인 원인:

JSON 오타(누락된 쉼표, 닫히지 않은 괄호)
args 배열의 잘못된 패키지 이름
누락되었거나 잘못된 환경 변수
네트워크/방화벽이 npx 패키지 설치를 차단함

디버그 단계:

JSON 검증: cat .mcp.json | jq .
명령 수동 테스트: npx -y @modelcontextprotocol/server-postgres "postgresql://..."
환경 확인: echo $GITHUB_TOKEN
구체적인 오류 메시지를 확인하려면 Verdent 로그를 검토합니다.

연동 워크플로

배울 내용

연동 방법

일반적인 연동 패턴

데이터베이스 개발 워크플로

보안을 포함한 API 개발

프론트엔드 접근성

MCP 설정 예시

MCP 이해하기

기본 설정

다중 환경

워크스페이스 연동

프로젝트별 설정

팀 협업

공유 AGENTS.md 표준

멀티 에이전트 조정

복잡한 기능 워크플로

연동 권장 사항

단계적 도입

전략적 조합

팀 문서화 권장 사항

문제 해결

함께 보기

확장성 가이드

MCP 연동

On this page