ai-agent-setup

AI 에이전트 거버넌스 시스템 — 워크플로우 규칙(agents/) + MCP RAG 서버(mcp-server/)

---

개요

AI 에이전트(Cursor, Cline, Antigravity 등)가 대규모 코드베이스를 효과적으로 다룰 수 있도록 행동 규칙과 컨텍스트 검색 인프라를 함께 제공합니다.

┌─────────────────────────────────────────────────────────┐
│                    AI Agent (Client)                    │
└───────────────┬─────────────────────┬───────────────────┘
                │ rules / workflows   │ MCP (stdio / SSE)
                ▼                     ▼
┌──────────────────────┐  ┌──────────────────────────────┐
│   agents/            │  │   mcp-server/ (Rust)         │
│   거버넌스 레이어      │  │   RAG 검색 레이어             │
│                      │  │                              │
│   rules/             │  │   BM25 + Vector + Graph      │
│   skills/            │  │   hybrid search              │
│   workflows/         │  │   stdio / SSE transport      │
└──────────────────────┘  └──────────────────────────────┘

---

구조

ai-agent-setup/
├── agents/                    # AI 거버넌스 레이어
│   ├── Makefile               # make deploy-all
│   ├── rules/                 # L2 공통 정책 + 도메인 룰
│   ├── skills/                # SKILL.md 재사용 스킬
│   └── workflows/
│       └── packs/             # YAML 워크플로우 팩
│           ├── session-lifecycle/   # /g-plan /handoff /resume /done
│           ├── micro-tasking/       # /run /m-plan /m-code /m-review
│           ├── validation/          # /review /rule-validator
│           ├── github/              # /github-pr /github-pr-review
│           └── jira/                # /jira-create /jira-status
│
└── mcp-server/                # MCP RAG 서버 (Rust)
    ├── src/
    │   ├── search/            # BM25, Vector, Hybrid, Fusion
    │   ├── tools/             # search_memory, domain_tools
    │   ├── transport/         # stdio, SSE
    │   ├── memory/            # collapser, compactor
    │   ├── core/              # decision_engine, registry
    │   └── observability/     # request_trace, telemetry
    ├── docker-compose.yml     # Neo4j + Redis + Ollama 스택
    └── Cargo.toml

---

시작하기

1. 에이전트 거버넌스 배포

# 현재 AI 도구(.agents/, .cursor/)에 워크플로우 배포
make -C agents deploy-all

# 배포 상태 확인
make -C agents status

2. MCP 서버 실행

cd mcp-server

# 환경 변수 설정
cp .env.example .env

# 서비스 시작 (Neo4j, Redis, Ollama 포함)
docker compose up

# SSE 모드 (원격 MCP 클라이언트)
docker compose up mcp-rust-sse

---

워크플로우 명령어

명령어	설명
/g-plan	전체 목표 계획 수립
/run	현재 상태 파악 후 자동 라우팅
/m-plan → /m-code → /m-review	단계형 작업 흐름
/handoff	세션 인수인계
/done	작업 완료 및 정리
/review	코드 리뷰
/rule-validator	규칙 기반 검증
/github-pr	PR 생성

---

기술 스택

레이어	기술
MCP 서버	Rust, Axum
검색	BM25 (SQLite), 벡터 유사도, Neo4j 그래프
에이전트 거버넌스	Markdown rules, YAML workflow packs
인프라	Docker Compose, Redis, Ollama

---

라이선스

MIT