엔터프라이즈급 프론트엔드 AI 코딩 에이전트 및 MCP 기반 자동화 시스템 - 제어된 계획(planning), 코드 생성, 브라우저 인식 실행(browser-aware execution) 및 리포지토리 워크플로우를 위해 사양 주도 개발 (Specification Driven Development, SDD)에 의해 제약됨

중문 문서 | 빠른 시작 | 아키텍처 | 설계 문서

FrontAgent는 프론트엔드 엔지니어링을 위한 오픈 소스 AI 코딩 에이전트입니다. 이 도구는 에이전트 방식의 CLI, VS Code 확장 프로그램, 데스크톱 앱, 로컬 MCP 서버, RAG 계획, 브라우저 인식 자동화 및 SDD 가드레일을 통해 팀이 웹 애플리케이션을 구축, 수정, 검증 및 배포할 수 있도록 지원합니다.

증류된 플래너 모델 (Distilled Planner Models): FrontAgent의 Planner 단계는 Hugging Face의 'FrontAgent: Frontend Engineering Agent' 아래 수집된 플래너 자산으로 증류되었습니다. 지원되는 Qwen Coder 베이스 모델에 게시된 어댑터를 로드하면 대규모 LLM API를 호출하지 않고도 프론트엔드 실행 계획을 직접 생성할 수 있습니다. 훈련 워크플로우, 프롬프트, 평가 스크립트 및 Hugging Face 릴리스 메타데이터는 models/frontagent-planner에 포함되어 있습니다.

다음과 같은 기능이 필요한 프론트엔드 AI 에이전트가 필요할 때 FrontAgent를 사용하세요:

구조화된 실행 계획으로부터 React, TypeScript, Vite, Tailwind CSS 및 현대적인 웹 UI 코드를 생성하고 리팩터링(refactor)합니다.

AI 에이전트 CLI, VS Code AI 확장 프로그램, 데스크톱 에이전트 앱, 또는 Claude Desktop, Cursor, Codex 및 기타 MCP 호스트를 위한 stdio MCP 서버로 실행됩니다.

리포지토리 인식 RAG, Filesense 탐색, 사실 메모리(facts memory) 및 모듈 의존성 추적을 결합하여 경로 환각(path hallucinations)을 줄입니다.

명시적인 안전 제어 하에 브라우저 인식 검증, 페이지 검사, 셸 명령 및 git/gh 리포지토리 워크플로우를 실행합니다.

프로덕션 프론트엔드 팀을 위해 사양 주도 개발 (Specification Driven Development, SDD), 최소 패치, 자가 치유 오류 복구 및 품질 게이트(quality gates)를 강제합니다.

로컬 또는 저비용 프론트엔드 실행 계획을 위해 Hugging Face의 증류된 Qwen Coder 플래너 모델을 사용합니다.

✅

2단계 아키텍처 (Two-Stage Architecture) - JSON 파싱 오류를 방지하고 동적 코드 생성을 가능하게 하기 위해 계획(planning)과 실행(execution)을 분리합니다 -
✅

단계 기반 실행 (Phase-Based Execution)

• 각 단계 내에서 오류 복구가 가능한 단계별 그룹화된 프로세스 -
  ✅

자가 치유 (Self-Healing)

• 도구 오류 피드백 루프 (Tool Error Feedback Loop)를 통해 오류를 자동으로 분석하고 수정 단계를 생성합니다 -
  ✅

사실 기반 메모리 (Facts Memory)

• 정확한 프로젝트 상태 추적을 위한 구조화된 사실 기반 컨텍스트 시스템 -
  ✅

모듈 의존성 추적 (Module Dependency Tracking)

• 경로 환각 (path hallucinations)을 탐지하기 위한 자동 import/export 파싱 -
  ✅

환각 방지 (Hallucination Prevention)

• 다층적 환각 탐지 및 차단 -
  ✅

SDD 제약 조건 (SDD Constraints)

• 에이전트 행동을 위한 하드 제약 조건으로서의 사양 주도 개발 (Specification Driven Development) -
  ✅

MCP 프로토콜 (MCP Protocol)

• 모델 컨텍스트 프로토콜 (Model Context Protocol)을 통한 제어된 도구 호출 -
  ✅

최소 변경 (Minimal Changes)

• 롤백(rollback)을 지원하는 패치 기반 코드 수정 -
  ✅

웹 인식 (Web Awareness)

• 브라우저 MCP를 통한 페이지 구조 이해 -
  ✅

셸 통합 (Shell Integration)

• 터미널 명령 실행 (사용자 승인 필요) -
  ✅

사전 계획 스캔 (Pre-Planning Scan)

• 정확한 파일 경로 생성을 위해 계획 수립 전 프로젝트 구조 스캔 -
  ✅

자동 포트 탐지 (Auto Port Detection)

• 설정 파일로부터 개발 서버 포트를 자동으로 탐지 -
  ✅

원격 하이브리드 RAG (Remote Hybrid RAG)

• 서브모듈을 제외한 전체 리포지토리 인덱싱을 수행하며, BM25 키워드 검색과 임베딩 기반 시맨틱 검색 (semantic search)을 결합합니다 -
  ✅

Filesense 내비게이션 (Filesense Navigation)

• 생성된 스키마와 노트를 활용하여 예산(budget)이 할당된 현재 리포지토리 내 탐색 수행 -
  ✅

LangGraph 엔진 (Optional)

• 선택적 체크포인트를 지원하는 전환 가능한 그래프 기반 실행 엔진 -
  ✅

Planner 기술 계층 (Planner Skills Layer)

• 작업 분해 및 단계 주입을 위한 재사용 가능한 계획 기술 -
  ✅

증류된 Planner 자산 (Distilled Planner Assets)

• Hugging Face Planner 모델 컬렉션을 위한 리포지토리 네이티브 훈련, 평가 및 릴리스 자산 -
  ✅

기술 연구소 (Skill Lab)

• 로컬 평가 스위트 (eval suites)를 통한 콘텐츠 기술의 벤치마크, 개선 및 승격 -
  ✅

VS Code 사이드바 (VS Code Sidebar)

• 작업 실행, SDD 도우미, 보안 설정 및 실행 로그를 포함하는 마켓플레이스 확장 프로그램 -
  ✅

OSS 하네스 (OSS Harness)

• 유지 관리자 친화적인 변경을 위한 로컬 계약, 품질, GitNexus 및 워크플로우 게이트 -
  ✅

저장소 관리 단계 (Repository Management Phase)

• 승인 후 자동 git/gh 워크플로우 실행 (commit, push, PR) -
  ✅

교차 세션 메모리 (Cross-Session Memory)

• 프로젝트 사실 관계, 오류 해결 방법, 의존성 상태를 실행 간에 유지하는 4단계 메모리 시스템 (preload, runtime recall, post-task persistence, structured storage)

현재 저장소는 npm CLI 패키지와 VS Code 확장 프로그램 모두 frontagent@2.1.1 버전에 맞춰져 있습니다.

• 런타임 요구 사항 (Runtime requirements): Node.js >=20.0.0, VS Code 확장 프로그램 엔진 ^1.120.0.
• 빌드 출력 (Build output): pnpm build를 실행하면 모노레포 (monorepo)를 빌드하고, CLI를 번들링하며, VS Code 버전을 동기화하고, apps/vscode/frontagent-2.1.1.vsix를 패키징합니다.
• 품질 게이트 (Quality gates): pnpm quality:predev, pnpm quality:precommit, pnpm quality:ci, 그리고 pnpm quality:local은 계약 검사 (contract checks), 린팅 (linting), 타입 체크 (typechecking), 테스트, 워크플로우 테스트 및 빌드 검증을 결합하여 수행합니다.
• v2.1.1 중점 사항: 더 작은 agent/executor/context/Filesense/memory/runtime/webview 모듈화, 강화된 VS Code webview nonce 생성, 복구된 GitNexus 계약 검사, 그리고 확장된 집중 테스트.

FrontAgent는 터미널, VS Code, 그리고 독립형 데스크톱 워크플로우를 지원합니다:

CLI: 터미널에서 직접 fa init, fa run, RAG 명령, Skill Lab 및 자동화 친화적인 워크플로우를 사용하세요.
VS Code 확장 프로그램 (VS Code Extension): FrontAgent 사이드바 작업 콘솔을 사용하여 작업을 실행하고, 현재 파일 또는 선택 영역을 첨부하며, 브라우저 URL을 제공하고, 단계/스텝 진행 상황을 검토하고, 민감한 작업을 승인하며, SDD를 초기화/검증하고, VS Code 내부에서 실행 로그를 여세요.
데스크톱 앱 (Desktop App): 동일한 Node 런타임 스파인 (spine)을 재사용하는 독립형 Electron GUI (apps/desktop)입니다. 작업을 실행하고, 실시간 단계/스텝 텔레메트리 (telemetry)를 모니터링하며, 민감한 작업을 승인하기 위한 작업 콘솔 (Task Console)과 LLM 제공자/모델 설정을 위한 설정 패널이 포함되어 있습니다.

Marketplace에서 FrontAgent 또는 확장 프로그램 ID ceilf6.frontagent를 검색하여 VS Code 확장 프로그램을 설치하세요.

데스크톱 클라이언트는 실제 런타임 (window.frontagent)에 연결된 샌드박스 처리된 Electron 창입니다.

→ IPC → runFrontAgentTask

); 이는 OS의 사용자 데이터 (user-data) 디렉토리에 설정을 저장하며, 런타임 (runtime)을 사용할 수 없는 경우에도 기능이 점진적으로 저하(degrades gracefully)될 뿐 작동은 유지됩니다.

다운로드 (Download): GitHub Releases 페이지(각 v* 태그에 대해 자동으로 게시됨)에서 플랫폼별 서명되지 않은 아카이브인 frontagent-desktop-${version}-${os}-${arch}.zip을 내려받아 압축을 풀고 frontagent 실행 파일을 실행하세요. LLM API 키는 환경 변수(PROVIDER_API_KEY / API_KEY)에서 읽어옵니다. 제공자(provider), 모델(model), 베이스 URL (base URL)은 앱 내 설정 (Settings) 패널에서 설정하세요.

로컬 빌드 (Build locally): pnpm --filter @frontagent/desktop package를 실행하면 apps/desktop/release/ 아래에 압축이 풀린 앱이 생성되며, pnpm --filter @frontagent/desktop dev를 통해 Vite 개발 서버 (dev server) 환경에서 실행할 수 있습니다. release 스크립트(pnpm --filter @frontagent/desktop run release)는 배포 가능한 zip 파일을 생성합니다.

데스크톱 아카이브는 현재 서명되지 않은 상태입니다. 코드 서명 (code signing), 공증 (notarization), 그리고 네이티브 설치 프로그램 (dmg/nsis/AppImage)은 향후 계획된 작업입니다.

# 1. npm을 통해 전역(globally) 설치
npm install -g frontagent
# 또는 pnpm 사용
...

FrontAgent는 Claude Desktop, Cursor, Codex 및 명령 기반 MCP 서버를 실행할 수 있는 기타 클라이언트와 같은 MCP 호스트 (MCP hosts)를 위한 로컬 stdio MCP 서버 (stdio MCP Server)로 실행될 수 있습니다.

MCP 모드는 FrontAgent의 상위 수준 에이전트 (agent) 기능만을 노출합니다. read_file, apply_patch, run_command, 브라우저 도구 (browser tools) 또는 rag_query와 같은 원시 내부 도구 (raw internal tools)를 외부 호스트에 직접 노출하지는 않습니다.

# 설치된 CLI 사용
fa mcp serve
# 또는 pnpm build 후 소스 체크아웃에서 실행
...

기본적으로 FrontAgent는 호스트가 정확히 하나의 파일 루트 (file root)를 노출할 때, MCP 호스트의 워크스페이스 루트 (workspace roots)로부터 프로젝트 루트 (project root)를 확인합니다. 호스트 루트를 사용할 수 없는 경우, MCP 서버 프로세스의 현재 작업 디렉토리 (current working directory)로 대체됩니다.

--project-root는 서버를 특정 프로젝트에 고정하고 싶을 때, 또는 호스트가 여러 워크스페이스 루트를 노출하여 FrontAgent가 안전하게 선택할 수 없는 경우에만 사용하세요:

fa mcp serve --project-root /absolute/path/to/your-project

하나의 MCP 서버 프로세스는 하나의 해결된 프로젝트 루트 (project root)에 바인딩됩니다.

유용한 서버 옵션:

fa mcp serve \
--engine native \
--security-mode balanced \
...

대부분의 MCP 호스트 (hosts)는 동일한 mcpServers 구조를 사용합니다. 간단한 설정부터 시작하세요:

{
"mcpServers": {
"frontagent": {
...

만약 호스트 UI에 별도의 필드가 있다면, 다음을 사용하세요:

• Command (명령어):
  fa

• Args (인자):
  mcp , serve

fa mcp serve를 하나의 문자열로 명령 필드에 넣지 마세요.

만약 호스트에서 command "fa" not found 또는 env: node: No such file or directory라는 오류를 보고한다면, GUI 호스트가 터미널 셸의 PATH를 상속받지 못하고 있을 가능성이 높습니다. 이 경우 절대 경로를 사용하세요:

which node
which fa

{
"mcpServers": {
"frontagent": {
...

전역으로 연결된 패키지 대신 소스 체크아웃 (source checkout)을 사용하는 경우, pnpm build 이후 빌드된 CLI 파일을 node가 가리키도록 설정하세요:

{
"mcpServers": {
"frontagent": {
...

직접적인 LLM 폴백 (fallback)을 위해, 호스트 설정을 통해 환경 변수 (environment variables)를 전달하세요:

{
"mcpServers": {
"frontagent": {
...

설정을 넣는 위치의 예시:

• Claude Desktop: claude_desktop_config.json 내의 mcpServers 아래에 서버를 추가합니다.
• Cursor: Cursor MCP 설정(예: .cursor/mcp.json) 내의 mcpServers 아래에 서버를 추가합니다.
• Codex 또는 기타 MCP 호스트: 호스트의 MCP 서버 설정 인터페이스에서 동일한 명령(command), 인자(args), 환경 변수(env) 값을 사용합니다.

FrontAgent는 6가지 MCP 도구 (tools)를 노출합니다:

frontagent_status: 프로젝트 루트, SDD 상태, 가시적인 기술 (skills), LLM 백엔드 상태, RAG 상태 및 실행 로그 (run-log) 디렉토리를 반환합니다.
frontagent_run_task: 전체 FrontAgent 작업을 실행합니다. 입력값에는 task, type, files, url, sddPath, securityMode가 포함됩니다.
frontagent_plan_task: 도구를 실행하거나 파일을 작성하지 않고 FrontAgent 실행 계획을 생성합니다.
frontagent_validate_sdd: 프로젝트 SDD 파일을 검증합니다.
frontagent_list_skills: 가시적인 콘텐츠 기술 (content skills) 목록을 나열합니다.
frontagent_init_sdd: SDD 템플릿을 생성합니다. force=true가 아닌 한 기존 파일은 덮어쓰지 않습니다.

frontagent_run_task는 다음과 같은 구조화된 JSON 텍스트를 반환합니다:

{
"success": true,
"taskId": "task_...",
...

MCP 모드는 auto를 사용합니다.

LLM 백엔드 선택:

• 호스트가 MCP Sampling을 지원하는 경우, FrontAgent는 sampling/createMessage를 통해 호스트 모델에 요청합니다.
• Sampling을 지원하지 않거나 사용할 수 없는 경우, FrontAgent는 직접적인 LLM 설정(direct LLM configuration)으로 폴백(fallback)합니다.

직접 폴백은 fa run과 동일한 환경 변수 및 플래그를 사용합니다:

export PROVIDER="openai"
export BASE_URL="https://api.openai.com/v1"
export MODEL="gpt-4"
...

frontagent_status, frontagent_list_skills, frontagent_validate_sdd, frontagent_init_sdd와 같은 읽기 전용 도구(Read-only tools)는 LLM 설정이 필요하지 않습니다. frontagent_run_task와 frontagent_plan_task는 호스트의 Sampling 지원 또는 유효한 직접 LLM 폴백이 필요합니다.

MCP 모드는 FrontAgent의 내부 보안 경계(internal safety boundary)를 유지합니다:

• 외부 MCP 호스트는 내부 파일, 셸(shell), 브라우저 또는 RAG 도구를 직접 호출할 수 없습니다.
• 내부 파일 쓰기, 셸 명령, 브라우저 동작 및 기타 부수 효과(side effects)는 여전히 SecurityManager를 거칩니다.
• 기본 보안 모드는 balanced입니다.
• stdio MCP는 FrontAgent의 대화형 승인 UI(interactive approval UI)를 제공하지 않으므로, ask 결정이 필요한 모든 작업은 실패 처리(fails closed)됩니다. frontagent_init_sdd는 구성된 프로젝트 루트 내부의 SDD 파일만 작성합니다.

FrontAgent는 이제 계획 및 코드 생성을 위한 전체 원격 저장소 지식 베이스(remote repository knowledge base) 흐름을 지원합니다:

• 원격 저장소를 .frontagent/rag-cache/repo로 동기화합니다.
• 전체 저장소를 청크(chunk) 단위로 인덱싱하며, Git 서브모듈(submodule) 경로는 자동으로 제외합니다.
• BM25 키워드 검색(keyword retrieval)과 임베딩 기반의 의미론적 검색(semantic retrieval)을 병렬로 실행합니다.
• 각 후보 목록에 메타데이터 필터(metadata filters)를 적용한 후, 순위가 매겨진 결과들을 융합(fuse)합니다.
• 구축된 인덱스와 임베딩 벡터는 .frontagent/rag-cache 아래에 캐싱됩니다.

기본 지식 소스:

• 저장소: https://github.com/ceilf6/Lab.git
• 소스 모드: git

기본값이며, FRONTAGENT_OPENVIKING_ENDPOINT가 설정되면 FrontAgent는 composite 모드를 기본값으로 사용합니다 (OpenViking을 우선적으로 사용하며, 실패 시 Git RAG로 폴백(fallback)합니다).

CLI 옵션:

fa run "Explain React setState behavior" \
--provider openai \
--base-url https://yunwu.ai/v1 \
...

FrontAgent에는 이제 skills/ 디렉토리 하위에서 콘텐츠 스킬(content skills)을 반복 개선할 수 있는 로컬 Skill Lab 워크플로우가 포함되어 있습니다.

# 가시적인 콘텐츠 스킬 목록 표시
fa skill list
# 새로운 콘텐츠 스킬 스캐폴딩(Scaffold)
...

현재 Skill Lab 흐름은 콘텐츠 스킬에 대해 두 가지 평가 트랙(eval tracks)을 지원합니다:

• 트리거 평가 (Trigger evals): 스킬이 올바르게 활성화되는지 여부.
• 동작 평가 (Behavior evals): 최종 출력 품질이 이진 검사(binary checks)를 통과하는지 여부.