Skip to content

AGENTS.md

Latest commit

 

History

History
383 lines (287 loc) · 19.9 KB

AGENTS.md

File metadata and controls

383 lines (287 loc) · 19.9 KB

AGENTS.md

Phase 6 레거시 정리 완료 이 프로젝트는 멀티 프로젝트 + 부서 기반 자율 에이전트 협업 시스템이다. 기존 단일 워크스페이스 + 고정 사이클(Chief→Lead→Member) 레거시 코드는 Phase 6에서 제거되었다. 다음 단계: 자율성 강화 + 멀티 도메인 확장 + 자체 모델 구축 — 24개월 로드맵 피벗 로드맵: roadmap/pivot-roadmap.md

이 문서는 로컬 웹 기반 Virtual AI Agent Company 프로젝트의 공통 운영 기준이다.

0) 모듈별 에이전트 문서 라우팅

이 프로젝트는 모놀리식 레포지토리다. 작업 대상 파일 경로를 보고, 아래 테이블에서 해당 모듈의 AGENTS.md를 먼저 참조한다. 각 모듈 AGENTS.md에는 세부 문서 라우팅 테이블이 있다.

작업 대상 경로 패턴 참조할 모듈 지침 핵심 원칙
mcp-server/** mcp-server/AGENTS.md Hexagonal + Clean Architecture + DDD + TDD (Rust/Axum)
web/** web/AGENTS.md Feature-Based Architecture (React 19 + Vite 7 + Zustand + TanStack Query)
rag-engine/** rag-engine/AGENTS.md Hybrid RAG Pipeline (Python/uv + ChromaDB + BM25)
rag-agent-core/** rag-agent-core/AGENTS.md RAG 컨텍스트 모델 (36 Query Patterns)
knowledge-base/** 이 파일 §2, §3, §7 단일 SoT (RAG 지식 베이스)
learning-engine/** learning-engine/AGENTS.md Self-Learning Engine (Python)
designsystem/** designsystem/AGENTS.md Material3 Design Tokens
tools/** tools/AGENTS.md 벤치마크 메트릭/분석 유틸리티

모듈별 세부 문서 인덱스

mcp-server (Rust/Axum 백엔드)

문서 읽어야 할 때
docs/architecture/README.md 아키텍처 개요, 레이어 구조 확인 시
docs/architecture/hexagonal-guide.md Port/Adapter 추가·변경, 의존 방향 확인 시
docs/architecture/package-structure.md 새 모듈/파일 추가 시
docs/domain/ddd-guide.md 도메인 모델, Entity, VO, Bounded Context 설계 시
docs/domain/usecase-guide.md UseCase/Application Service 작성 시
docs/testing/tdd-guide.md TDD 워크플로우 확인 시
docs/rust/async-guide.md Tokio 비동기 패턴 확인 시
docs/axum/handler-guide.md HTTP/WebSocket 핸들러 작성 시
docs/convention/api-design-guide.md API 설계, 응답 형식 확인 시

web (React 프론트엔드)

문서 읽어야 할 때
docs/architecture/README.md 전체 구조, 레이어 규칙 확인 시
docs/architecture/folder-structure.md 폴더 구조, 네이밍 확인 시
docs/react/component-guide.md 컴포넌트 작성 시
docs/react/state-guide.md 상태 관리 전략 확인 시
docs/zustand/store-guide.md Zustand 스토어 작성 시
docs/tanstack-query/query-guide.md TanStack Query 사용 시
docs/typescript/type-guide.md 타입 규칙 확인 시

rag-engine (Python RAG 파이프라인)

문서 읽어야 할 때
docs/architecture/README.md 파이프라인 구조 확인 시
docs/architecture/pipeline-guide.md 인덱싱/검색 로직 수정 시
docs/python/naming-guide.md 네이밍 규칙 확인 시

rag-agent-core (RAG 컨텍스트 모델)

문서 읽어야 할 때
docs/architecture/README.md 36 쿼리 패턴, 역할별 검색 설정 확인 시

learning-engine (자기 학습 엔진)

문서 읽어야 할 때
docs/architecture/README.md 전체 학습 파이프라인, 출력 경로 확인 시
docs/cli/command-guide.md CLI 서브커맨드 추가/수정 시
docs/ml/training-guide.md RL/DL/Evolution/Meta 로직 수정 시
docs/python/naming-guide.md Python 네이밍 및 모듈 분리 규칙 확인 시

designsystem (디자인 토큰)

문서 읽어야 할 때
docs/architecture/README.md 토큰 패키지 구조, 산출물 확인 시
docs/tokens/token-guide.md 토큰 추가/수정, 네임스페이스 규칙 확인 시
docs/build/build-guide.md 빌드 스크립트/출력 포맷 수정 시

tools (메트릭/벤치마크 유틸리티)

문서 읽어야 할 때
docs/architecture/README.md tools/metrics/ 구조, 입력/출력 확인 시
docs/metrics/benchmark-guide.md KPI 계산, 벤치마크 포맷 수정 시
docs/node/cli-guide.md Node CLI 패턴, 인자 파싱 수정 시

추가 모듈 참조

모듈 진입점 참조 시점
docs docs/operations/ 빠른 시작·트러블슈팅 가이드 확인 시

우선순위 규칙

우선순위 문서
1 (최우선) 이 파일 (루트 AGENTS.md) — 프로젝트 공통 규칙
2 모듈 AGENTS.md — 모듈별 아키텍처·코딩 규칙
3 모듈 docs/** — 세부 가이드
4 CLAUDE.md / GEMINI.md — 에이전트별 진입점

1) 프로젝트 목표

로컬 환경에서 여러 AI 에이전트(claude, gemini, codex)를 실제 회사 조직처럼 운영하는 시스템이다.

핵심 목표

목표 설명
멀티 프로젝트 관리 여러 프로젝트를 생성하고, 각 프로젝트에 부서와 에이전트를 배치
부서 기반 협업 프로젝트 → 부서 → 에이전트 계층으로 조직, 부서 간 협업은 제안(Proposal) 시스템으로 관리
태스크 기반 실행 부서별 태스크를 생성·실행·추적, 에이전트가 자율적으로 태스크를 처리
자연어 채팅 인터페이스 프로젝트별 채팅으로 지시를 내리면 자동으로 태스크 생성·분배·실행
RAG 기반 컨텍스트 Knowledge Base에서 필요한 청크만 동적 검색
자기 학습 에피소드 기록 → 인사이트 축적 → 프롬프트 최적화
실시간 모니터링 WebSocket 스트림으로 프로젝트별 진행률, 로그 실시간 추적

기술 스택 요약

모듈 기술 역할
mcp-server Rust 2024 + Axum 0.8 + Tokio 1.44 프로젝트 오케스트레이션, REST/WebSocket API (:4070)
web React 19 + Vite 7 + Zustand 5 + TanStack Query 5 운영 대시보드 (:5173)
rag-engine Python 3.10+ + ChromaDB + BM25 하이브리드 검색 파이프라인 (Dense + Sparse RRF)
rag-agent-core Markdown/YAML RAG 컨텍스트 모델 (36 쿼리 패턴, 역할별 검색 설정)
knowledge-base Markdown (RAG-indexed) 단일 SoT — 페르소나, 역할, 거버넌스, 기술 문서
learning-engine Python 3.10+ + PyTorch + stable-baselines3 자기 학습 — 진화적 프롬프트, 메타 러닝, RL 오케스트레이터
designsystem Node.js + DTCG 토큰 Material 3 디자인 토큰 → CSS/Android/iOS 빌드
scripts Bash/Python 운영 스크립트, 검증 스크립트, A/B 벤치마크
tools Node.js + JSON 템플릿 벤치마크 실행, KPI 집계, 결과 검증

2) 디렉토리 규칙 (Mandatory)

전체 모듈 맵

디렉토리 역할 기술 세부 지침
mcp-server/ 프로젝트 오케스트레이션, REST/WebSocket API Rust 2024, Axum 0.8, Tokio 1.44 mcp-server/AGENTS.md
web/ 운영 대시보드 UI React 19, Vite 7, Zustand 5, TanStack Query 5 web/AGENTS.md
rag-engine/ 하이브리드 검색 파이프라인 Python, ChromaDB, BM25, uv rag-engine/AGENTS.md
rag-agent-core/ RAG 컨텍스트 모델 (36 쿼리 패턴) Markdown/YAML rag-agent-core/AGENTS.md
knowledge-base/ 단일 SoT — 에이전트 지식 베이스 Markdown (RAG-indexed) 이 파일 §7
learning-engine/ 자기 학습 엔진 (진화 프롬프트, RL, DL) Python, PyTorch, stable-baselines3 learning-engine/AGENTS.md
designsystem/ Material 3 디자인 토큰 빌드 Node.js, DTCG format designsystem/AGENTS.md
scripts/ 운영·검증·벤치마크 스크립트 Bash/Python —
tools/ 벤치마크 메트릭 템플릿 Node.js, JSON tools/AGENTS.md

knowledge-base/ — 단일 SoT (RAG 지식 베이스)

  • 에이전트 페르소나·역할·거버넌스·기술 문서를 RAG 최적화 구조로 통합한다.
  • 하위 도메인: agents/, governance/, operations/, technical/, rag-pipeline/, history/
  • RAG 인덱싱 설정: _rag-config/ (domain-taxonomy, chunking-rules, index-manifest)
  • 에이전트는 이 KB에서 역할×단계에 필요한 청크만 동적으로 검색한다.

rag-agent-core/ — 에이전트 RAG 컨텍스트 모델

  • 에이전트가 RAG를 활용하여 컨텍스트를 동적으로 조립하는 방법을 정의한다.
  • 하위: context-model/, retrieval-specs/, knowledge-base-ops/
  • 역할(Chief/Lead/Member) × 단계(PLAN/WORK/REVIEW/COMPOUND) × 질문 유형(3) = 36가지 표준 쿼리 패턴 포함.

rag-engine/ — 로컬 RAG 파이프라인 (Python/uv)

  • knowledge-base/를 인덱싱하고 하이브리드 검색(Dense + BM25 RRF)을 제공한다.
  • 진입점: rag-engine/cli.py (ingest / search / status)
  • 임베딩 우선순위: OpenAI > Gemini > 로컬 sentence-transformers (자동 감지)
  • 스토리지: ChromaDB (data/.chroma/) + BM25 (data/bm25_index.pkl)
  • 사용법: 
    cd rag-engine && uv sync
uv run --project rag-engine rag-engine/cli.py ingest
uv run --project rag-engine rag-engine/cli.py search "query" --role chief --stage plan --top-k 5
uv run --project rag-engine rag-engine/cli.py status

learning-engine/ — 자기 학습 엔진 (Python)

  • 에피소드 기반 학습 데이터 추출, RL 오케스트레이터 훈련, DL 품질 예측을 제공한다.
  • 진화적 프롬프트 최적화: 게놈 초기화(evo-init) → 선택(evo-select) → 진화(evo-evolve)
  • 메타 러닝: 병목 감지(meta-analyze), A/B 테스트 관리(meta-status)
  • 진입점: learning-engine/learning_engine/cli.py (13개 서브커맨드)
  • 데이터 출력: {workdir}/.agentCompany/learning-data/

designsystem/ — Material 3 디자인 토큰

  • SoT 토큰: tokens/material3.tokens.json (DTCG 형식)
  • 빌드: scripts/build.mjs → CSS/Android/iOS/Portable 4개 플랫폼 출력
  • 웹 동기화: cd web && npm run sync:designsystem-css

tools/ — 메트릭/벤치마크 유틸리티

  • 하위 도메인: tools/metrics/
  • 포맷: Node.js ESM CLI + JSON 템플릿
  • 주요 유틸리티: KPI 집계(benchmark-ab-kpi.mjs), 벤치마크 실행(run-benchmark-ab.mjs), 태스크셋 검증(validate-benchmark-set.mjs)

2-1) .agentCompany/ 데이터 구조

프로젝트 데이터는 ~/.agentCompany/projects/ 하위에 저장된다.

프로젝트 데이터 경로

~/.agentCompany/projects/{project-id}/
├── project.json
├── departments/{dept-id}/
│   ├── department.json
│   ├── agents/{agent-id}.json
│   ├── tasks/{task-id}.json
│   └── episodes/
├── proposals/{proposal-id}.json
└── shared-contexts/{context-id}.json

마이그레이션

서버 시작 시 기존 settings.json/agents.json이 있으면 자동으로 새 프로젝트 구조로 마이그레이션한다.

3) 문서 생성 규칙

Knowledge Base 문서

상황 생성할 문서 위치
신규 에이전트 생성 페르소나 문서 knowledge-base/agents/personas/<agent-name>.md
신규 에이전트 생성 역할 문서 knowledge-base/agents/roles/<role-name>.md
프로젝트 정책 추가/변경 거버넌스 또는 기술 문서 knowledge-base/governance/ 또는 knowledge-base/technical/
운영 절차 추가/변경 운영 문서 knowledge-base/operations/
RAG 파이프라인 변경 RAG 설계 문서 knowledge-base/rag-pipeline/

모듈 개발 문서

상황 생성할 문서 위치
mcp-server에 새 Adapter 추가 아키텍처 가이드 갱신 mcp-server/docs/architecture/README.md 인덱스 등록
mcp-server에 새 API 엔드포인트 추가 API 설계 문서 갱신 mcp-server/docs/convention/api-design-guide.md
web에 새 Feature 모듈 추가 폴더 구조 가이드 갱신 web/docs/architecture/folder-structure.md
rag-engine에 새 모듈 추가 파이프라인 가이드 갱신 rag-engine/docs/architecture/pipeline-guide.md
learning-engine에 새 학습 서브시스템 추가 아키텍처/CLI 가이드 갱신 learning-engine/docs/architecture/README.md, learning-engine/docs/cli/command-guide.md
designsystem에 새 토큰 네임스페이스 추가 토큰/빌드 가이드 갱신 designsystem/docs/tokens/token-guide.md, designsystem/docs/build/build-guide.md
tools에 새 메트릭 CLI 추가 벤치마크 가이드 갱신 tools/docs/metrics/benchmark-guide.md

공통 규칙

  • 파일명은 kebab-case를 사용한다.
  • KB 문서 추가/수정 후 반드시 재인덱싱한다: 
    uv run --project rag-engine rag-engine/cli.py ingest --domain <domain>
  • KB 문서 추가 시 knowledge-base/_rag-config/index-manifest.yaml에 엔트리를 등록한다.

4) 에이전트 정의

에이전트는 프로젝트 내 부서에 소속된다. API: POST /api/v1/projects/{id}/departments/{dept_id}/agents

에이전트 필드 (API)

필드 필수 설명
name Y 에이전트 이름
agent_type Y AI 프로바이더 (claude, gemini, codex)
role Y 부서 내 역할
persona N 페르소나 요약
model_id N 모델 지정

Knowledge Base 문서 (선택)

에이전트 페르소나·역할 정보를 KB에 보관할 수 있다:

  • 페르소나: knowledge-base/agents/personas/<agent-name>.md
  • 역할: knowledge-base/agents/roles/<role-name>.md

5) 협업 규칙

태스크 기반 실행 모델

단계 설명
태스크 생성 사용자가 채팅 또는 API로 지시 → 부서별 태스크 자동 생성
태스크 실행 부서 내 에이전트가 태스크를 자율적으로 처리
크로스 부서 협업 부서 간 의존성은 제안(Proposal) 시스템으로 조율
학습 피드백 에피소드 기록 → 인사이트 축적

실행 규칙

  • 에이전트 간 의사소통은 부서 내 메시지 시스템과 에피소드 기록으로 추적한다.
  • 크로스 부서 의존성 발생 시 Proposal을 생성하여 승인 후 실행한다.
  • 충돌하는 결정이 발생하면 이 AGENTS.md를 우선 기준으로 해소한다.

학습 루프

  • 태스크 완료 시 에피소드를 기록하고 인사이트를 축적한다.
  • 에피소드 기반으로 에이전트 메모리를 업데이트한다.

6) 우선순위 규칙

우선순위 대상 설명
1 knowledge-base/ 모든 에이전트 지식의 단일 SoT
2 이 파일 (AGENTS.md) 프로젝트 공통 운영 규칙
3 모듈 AGENTS.md 모듈별 아키텍처·코딩 규칙
4 rag-engine/ RAG 인덱스 관리 (ChromaDB + BM25)
5 learning-engine/ 학습 데이터·모델 관리

7) RAG 컨텍스트 모델

배경: 에이전트가 57개 파일(158KB)을 전체 로드하는 방식에서, Advanced RAG로 필요한 청크만 동적 검색하는 방식으로 전환한다.

7-1. Knowledge Base 구조

경로 역할
knowledge-base/_rag-config/ 인덱싱 설정 (도메인 분류, 청킹 규칙, 인덱스 매니페스트)
knowledge-base/agents/ 페르소나, 역할, 소통 프로토콜 (docs/agents/ 미러)
knowledge-base/governance/ 조직, 헌장, 승인 규칙, Chiefs (통합)
knowledge-base/operations/ 세션 관리, CEO 지휘 절차
knowledge-base/technical/ 아키텍처, API, 보안, 배포, 실험
knowledge-base/technical/experiments/ 운영 모드 실험 문서
knowledge-base/rag-pipeline/ RAG 설계 (아키텍처, 청킹, 검색)
knowledge-base/history/ 계획/솔루션/리뷰 아카이브

7-2. 에이전트 컨텍스트 조립 원칙

  1. 역할 기반 검색 — Chief/Lead/Member별로 검색 도메인과 Top-K가 다르다.
  2. 단계 기반 쿼리 — PLAN/WORK/REVIEW/COMPOUND 단계마다 표준 쿼리 패턴 사용.
  3. 최소 컨텍스트 — 역할+단계에 필요한 최소 청크만 로드 (5~15KB).
  4. 요약으로 찾고, 원본으로 읽는다 — 검색은 summary 인덱스, LLM 입력은 원본 청크.

7-3. 표준 쿼리 패턴

역할(Chief/Lead/Member) × 단계(PLAN/WORK/REVIEW/COMPOUND) × 질문 유형(3가지)의 36가지 표준 쿼리 패턴은 아래에서 확인: → rag-agent-core/context-model/query-patterns.md

7-4. 문서 생성/수정 시 KB 갱신 규칙

  • knowledge-base/ 하위 문서를 추가/수정하면:
    1. knowledge-base/_rag-config/index-manifest.yaml에 엔트리를 추가한다.
    2. 증분 인덱싱을 실행한다: 
      uv run --project rag-engine rag-engine/cli.py ingest --domain <domain>

7-5. 관련 문서

8) 제안(Proposal) 시스템

크로스 부서 협업이 필요할 때 Proposal을 생성하여 승인 흐름을 거친다.

API

엔드포인트 설명
POST /api/v1/projects/{id}/proposals 제안 생성
GET /api/v1/projects/{id}/proposals 제안 목록
POST /api/v1/projects/{id}/proposals/{pid}/approve 제안 승인 → 관련 태스크 자동 생성

흐름

  1. 부서 A의 에이전트가 부서 B의 리소스/작업이 필요하다고 판단
  2. Proposal 생성 (source_department, target_department, description)
  3. 사용자 또는 시스템이 Proposal 승인
  4. 승인 시 target_department에 태스크가 자동 생성됨