/pm # PM 에이전트 시작 (자동 상태 복구)
/ci start # CI/CD 세션 시작 (헬스체크 포함)
/ci auto 5 # 자동 모드로 5개 작업 연속 실행1. PLAN.md 읽기 → "다음 세션 우선 작업" 섹션 확인
2. PROGRESS.md 읽기 → "현재 진행 상황" 섹션 확인
3. /health → 시스템 상태 확인
4. /queue next → 다음 작업 확인
현재 상태 (2026-02-20):
- ✅ PM 자동화 시스템 완성 (상태관리, 스케줄링, 피드백, 알림)
- ✅ CI/CD 통합 시스템 구축 (지속적 실행, 헬스체크, 파이프라인)
- ✅ GitHub 이슈/PR 자동화 (이슈 분석, PR 생성, 기술 보고서)
- ✅ 이력 기반 멀티 에이전트 오케스트레이션 (pm-orchestrate)
- ✅ Phase 1 완료 (테스트 1,511개 모두 통과)
┌─────────────────────────────────────────────────────────────────────────┐
│ PM Agent (Orchestrator) │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌──────────────┐ ┌─────────────┐ ┌────────────┐ │
│ │ state- │ │ work- │ │ feedback- │ │ health- │ │
│ │ manager │ │ scheduler │ │ loop │ │ checker │ │
│ └──────┬──────┘ └──────┬───────┘ └──────┬──────┘ └─────┬──────┘ │
│ └────────────┬────┴──────────────────┼────────────────┘ │
│ ▼ ▼ │
│ ┌───────────────────────────────────────────────────────────────────┐ │
│ │ pm-orchestrate (이력 기반) │ │
│ │ execution-patterns.json → 레시피 선택 → 병렬 에이전트 실행 │ │
│ └───────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌───────────────────┴───────────────────────────────────────────────┐ │
│ │ Execution Layer (병렬 실행) │ │
│ ├─────────────┬─────────────┬─────────────┬─────────────────────────┤ │
│ │ tdd- │ task- │ code- │ security- │ │
│ │ guide │ executor │ reviewer │ reviewer │ │
│ └─────────────┴─────────────┴─────────────┴─────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
Claude Code가 세션을 시작할 때:
1. /health quick # 빠른 헬스 체크
2. state-manager.restore() # 이전 상태 복구
3. work-scheduler.sync() # GitHub/PLAN.md 동기화
4. feedback-loop.load() # 관련 패턴/인사이트 로드
5. PM 작업 선택 또는 대기
| 커맨드 | 설명 | 사용 시점 |
|---|---|---|
/pm |
PM 에이전트 시작 | 세션 시작 시 |
/pm-orchestrate |
이력 기반 멀티 에이전트 실행 | 복잡한 작업 시 |
/ci start |
CI 세션 시작 (대화형) | 작업 시작 시 |
/ci auto N |
N개 작업 자동 실행 | 연속 작업 시 |
/health |
시스템 상태 확인 | 문제 발생 시 |
/queue |
작업 대기열 확인 | 다음 작업 확인 |
/state |
상태 저장/복구 | 세션 전환 시 |
/feedback |
패턴/인사이트 확인 | 작업 전 참고 |
/notify |
알림/리포트 확인 | 진행 확인 시 |
/ci start- 각 작업 완료 후 사용자 확인
- 안전한 기본 모드
/ci auto 5 # 5개 작업 자동 실행
/ci auto --no-limit # 무제한 실행- 사용자 확인 없이 연속 실행
- 에러 시 자동 일시정지
/ci watch- GitHub 이벤트 감시
- 새 이슈 감지 시 자동 처리
GitHub 이슈 등록
│
▼
┌─────────────────────┐
│ issue-manager │ → 이슈 분석/라벨링
│ (1시간마다 동기화) │ → PM 코멘트 추가
└─────────────────────┘
│
▼
┌─────────────────────┐
│ work-scheduler │ → 우선순위 정렬
│ │ → 의존성 확인
└─────────────────────┘
│
▼
┌─────────────────────┐
│ issue-developer │ → 브랜치 생성
│ │ → 코드 구현
│ │ → 코드 리뷰
│ │ → 검증
│ │ → PR 생성
└─────────────────────┘
│
▼
┌─────────────────────┐
│ technical-writer │ → 기술 보고서 작성
│ │ → LessonLearn/ 저장
└─────────────────────┘
│
▼
다음 작업 자동 시작
.claude/config.json- 전체 시스템 설정.claude/state/- 상태 파일들.claude/pipelines/- CI/CD 파이프라인 정의.claude/triggers/- 외부 트리거 파일
| 레벨 | 조치 | 예시 |
|---|---|---|
| 자동 재시도 | 3회까지 재시도 | 빌드 실패, 네트워크 |
| 롤백 | 체크포인트 복구 | 코드 리뷰 실패 |
| 스킵 | 다음 작업 진행 | 최대 재시도 초과 |
| 중단 | 수동 개입 요청 | 복구 불가 에러 |
PM 에이전트가 자율 운영 중 따라야 할 루프 규칙입니다.
루프 진입 조건:
- /ci auto N 또는 /ci auto --no-limit 실행 시
- 외부 트리거(.claude/triggers/queue/) 파일 감지 시
루프 실행 규칙:
1. 블로커(blocker) 없으면 다음 작업으로 계속 진행
2. 5턴마다 /compact 실행 → 컨텍스트 압축 및 정리
3. 10턴마다 체크포인트 저장 → .claude/state/checkpoint-{timestamp}.json
블로커 정의 (루프 일시 정지 조건):
- 빌드 실패 3회 연속
- 테스트 커버리지 80% 미달
- 보안 이슈 CRITICAL 발견
- 작업 대기열이 비어 있음
- 수동 개입 요청 플래그 감지
작업 완료 시 자동으로 커밋을 생성합니다.
커밋 트리거:
- 기능 구현 완료 (테스트 통과 후)
- 버그 수정 완료 (검증 후)
- 리팩토링 완료 (빌드 통과 후)
커밋 메시지 컨벤션:
feat: 새 기능 추가
fix: 버그 수정
test: 테스트 추가/수정
docs: 문서 업데이트
refactor: 코드 리팩토링
chore: 빌드/설정 변경
perf: 성능 개선
ci: CI/CD 설정 변경
커밋 작성자 규칙:
- 작성자: Mario Cho <hephaex@gmail.com> 단독
- Co-Authored-By 줄 추가 금지
- AI 생성 표시 문구 추가 금지
- 커밋 메시지는 영문으로 작성 (본문은 한국어 허용)
커밋 실행 예시:
git add {변경된_파일들}
git commit -m "$(cat <<'EOF'
feat: add vector embedding storage for documents
pgvector 기반 문서 임베딩 저장 및 검색 기능 구현
- DocumentEmbedding 모델 정의
- embedding_service.rs 구현
- /api/embeddings 라우트 추가
EOF
)"레벨별 복구 전략과 최대 재시도 횟수를 정의합니다.
| 레벨 | 이름 | 조건 | 복구 전략 | 최대 재시도 |
|---|---|---|---|---|
| L1 | 자동 재시도 | 일시적 실패 (빌드, 네트워크) | 즉시 재시도 | 3회 |
| L2 | 롤백 | 코드 리뷰 실패, 테스트 실패 | 마지막 체크포인트로 복구 | 2회 |
| L3 | 스킵 | L1/L2 최대 재시도 초과 | 현재 작업 건너뛰고 다음 진행 | - |
| L4 | 중단 | 보안 이슈, 복구 불가 에러 | 루프 중단 + 수동 개입 요청 | - |
롤백 조건:
- cargo clippy 에러 3회 연속 수정 실패
- 테스트 커버리지가 80% 아래로 하락
- API 통합 테스트 2회 연속 실패
롤백 절차:
1. 현재 변경사항 git stash
2. 마지막 성공 체크포인트 로드
3. .claude/state/current-task.json 상태를 "failed"로 업데이트
4. 작업을 work-queue.json 맨 뒤로 이동 (재시도 카운터 증가)
5. 다음 작업 선택
L4 중단 시 알림:
- .claude/triggers/queue/manual-intervention-required.json 생성
- PROGRESS.md에 블로커 내용 기록
| 파일 | 역할 | 갱신 주기 |
|---|---|---|
.claude/state/current-task.json |
현재 실행 중인 작업 | 작업 시작/완료 시 |
.claude/state/work-queue.json |
대기 중인 작업 목록 | 작업 추가/완료 시 |
.claude/state/agent-context.json |
에이전트 공유 컨텍스트 | 5턴마다 |
.claude/state/feedback.json |
패턴/인사이트 누적 | 작업 완료 시 |
.claude/state/ci-session.json |
현재 CI 세션 정보 | 실시간 |
.claude/state/checkpoint-{ts}.json |
10턴 주기 스냅샷 | 10턴마다 |
세션 복구 순서:
1. .claude/state/ci-session.json 읽기 → 마지막 세션 상태 확인
2. .claude/state/current-task.json 읽기 → 중단된 작업 확인
3. .claude/state/work-queue.json 읽기 → 대기열 상태 복구
4. .claude/state/agent-context.json 읽기 → 공유 컨텍스트 로드
5. 중단된 작업이 있으면 재개, 없으면 대기열 맨 앞 작업 시작
컨텍스트 압축 (/compact 트리거, 5턴마다):
- 완료된 작업 요약을 agent-context.json에 저장
- 오래된 상세 로그는 .history/에 아카이브
- 현재 작업 컨텍스트만 메모리에 유지
Sub-agent는 아래 JSON 구조로 결과를 반환해야 합니다.
{
"agent": "agent-name",
"task_id": "task-uuid",
"status": "success | failure | partial",
"result": {
"summary": "작업 결과 한줄 요약",
"artifacts": ["생성된 파일 절대경로 목록"],
"metrics": {
"files_changed": 0,
"lines_added": 0,
"lines_removed": 0,
"tests_added": 0
}
},
"next_action": "continue | review | commit | rollback | stop",
"error": null
}| 코드 | 이름 | 의미 | 대응 |
|---|---|---|---|
E001 |
BUILD_FAIL | 빌드 실패 | L1 재시도 |
E002 |
TEST_FAIL | 테스트 실패 | L1 재시도 |
E003 |
COVERAGE_LOW | 커버리지 80% 미달 | L2 롤백 |
E004 |
LINT_FAIL | clippy/eslint 실패 | L1 재시도 |
E005 |
REVIEW_FAIL | 코드 리뷰 CRITICAL | L2 롤백 |
E006 |
SECURITY_ISSUE | 보안 취약점 발견 | L4 중단 |
E007 |
CONFLICT | git 충돌 | L2 롤백 |
E008 |
TIMEOUT | 작업 타임아웃 (30분) | L3 스킵 |
E009 |
QUEUE_EMPTY | 대기열 비어 있음 | 루프 종료 |
E010 |
UNKNOWN | 알 수 없는 에러 | L4 중단 |
Orchestrator → Sub-agent:
.claude/triggers/queue/{task-id}.json
Sub-agent → Orchestrator:
.claude/triggers/processed/{task-id}-result.json
형식:
{
"task_id": "uuid",
"agent": "issue-developer",
"command": "implement",
"payload": { ... },
"timeout_minutes": 30
}
세션 시작 시 반드시 아래 파일들을 먼저 읽으세요:
1. PLAN.md → 무슨 일을 해야 하는지 (할 일 목록)
2. PROGRESS.md → 어디까지 진행되었는지 (완료된 작업)
세션 시작
│
├─→ PLAN.md 읽기 (할 일 확인)
├─→ PROGRESS.md 읽기 (진행 상황 확인)
│
▼
작업 수행
│
├─→ 작업 완료 시: PROGRESS.md 업데이트
├─→ 새 할 일 발견 시: PLAN.md 업데이트
│
▼
세션 종료
│
└─→ .history/YYYY-MM-DD_description.md에 상세 로그 저장
| 파일 | 목적 | 업데이트 시점 |
|---|---|---|
PLAN.md |
해야 할 일, 우선순위, 담당 | 새 작업 추가/완료 시 |
PROGRESS.md |
완료된 작업, 결정사항, 이슈 | 작업 완료마다 |
.history/*.md |
상세 세션 로그 | 세션 종료 시 |
MinKy는 3~9명 소규모 팀의 암묵지(tacit knowledge)를 형식지로 전환하고, 팀원 누구나 필요할 때 자연어로 찾아 활용할 수 있게 하는 지식 플랫폼입니다.
암묵지 → 캡처 → AI 이해 → 연결 → 자연어 검색 → 팀 성장
- 태그/분류가 아닌 이해: AI가 문서를 "읽고 이해"하여 자동으로 연결
- 검색이 아닌 대화: "이거 어디있지?" 대신 "우리 팀에서 이런 문제 해결한 적 있어?"
- 개인 성장 → 팀 성장: 한 사람의 학습이 팀 전체의 자산이 됨
┌─────────────────────────────────────────────────────────────┐
│ Input Sources │
├─────────────┬─────────────┬─────────────┬──────────────────┤
│ Obsidian │ Safari │ Slack │ Direct Input │
│ Markdown │ Clipper │ Messages │ Chat/Upload │
└──────┬──────┴──────┬──────┴──────┬──────┴────────┬─────────┘
│ │ │ │
└─────────────┴──────┬──────┴───────────────┘
▼
┌─────────────────────────────────────────────────────────────┐
│ Knowledge Pipeline │
├─────────────────────────────────────────────────────────────┤
│ 1. Document Ingestion │
│ - Markdown/HTML/PDF parsing │
│ - Metadata extraction │
│ │
│ 2. AI Understanding (Claude) │
│ - 핵심 주제 추출 │
│ - 해결한 문제 식별 │
│ - 관련 기술/도구 태깅 │
│ - 연결 가능한 지식 파악 │
│ │
│ 3. Vector Embedding │
│ - Document embeddings │
│ - Chunk-level embeddings │
│ - Semantic indexing │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Knowledge Store │
├──────────────────────┬──────────────────────────────────────┤
│ PostgreSQL │ Vector DB (pgvector/Qdrant) │
│ - Documents │ - Embeddings │
│ - Metadata │ - Semantic search │
│ - Relations │ - Similarity matching │
└──────────────────────┴──────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ RAG Search Layer │
├─────────────────────────────────────────────────────────────┤
│ User Question → Query Understanding → Vector Search │
│ → Context Assembly → Claude Generation → Answer │
└─────────────────────────────────────────────────────────────┘
- Framework: Axum 0.8
- Database: PostgreSQL + pgvector
- Vector Search: pgvector (primary) / Qdrant (optional)
- AI: Claude API (Anthropic)
- Embedding: OpenAI text-embedding-3-small / Voyage AI
- Async Runtime: Tokio
- Framework: React 18+
- State: React Query / Zustand
- UI: Tailwind CSS + shadcn/ui
- Chat: Real-time WebSocket
- Container: Docker
- DB Migration: sqlx-cli
- CI/CD: GitHub Actions
minky/
├── CLAUDE.md # 프로젝트 가이드 (이 파일)
├── .history/ # 세션 로그
├── BK/ # 백업 파일
├── Docs/ # 문서
│
├── app/ # Python Backend (Legacy)
│ ├── middleware/
│ ├── models/
│ ├── routes/
│ ├── schemas/
│ ├── services/
│ │ ├── agents/ # AI 에이전트
│ │ └── llm_providers/ # LLM 제공자
│ └── utils/
│
├── minky-rust/ # Rust Backend (Active)
│ ├── Cargo.toml
│ ├── migrations/ # SQL 마이그레이션
│ └── src/
│ ├── main.rs
│ ├── lib.rs
│ ├── config.rs
│ ├── error.rs
│ ├── middleware/ # 인증, 로깅
│ ├── models/ # 데이터 타입, 스키마
│ ├── routes/ # API 엔드포인트
│ ├── services/ # 비즈니스 로직
│ └── utils/
│
├── frontend/ # React Frontend
│ ├── public/
│ └── src/
│ ├── components/ # UI 컴포넌트
│ ├── hooks/ # 커스텀 훅
│ ├── pages/ # 페이지
│ ├── services/ # API 클라이언트
│ ├── styles/ # CSS/Tailwind
│ ├── utils/ # 유틸리티
│ └── i18n/ # 다국어
│
├── tests/ # Python 테스트
├── migrations/ # Python DB 마이그레이션
├── logs/ # 로그 파일
│
└── .claude/ # Claude Code 설정
├── agents/ # 에이전트 정의 (21개)
├── commands/ # 커맨드 정의 (23개)
├── skills/ # 스킬 정의 (6개)
├── config.json # 전체 시스템 설정
├── state/ # 상태 관리
│ ├── current-task.json
│ ├── work-queue.json
│ ├── agent-context.json
│ ├── feedback.json
│ └── ci-session.json
├── locks/ # 동시 작업 잠금
├── pipelines/ # CI/CD 파이프라인 정의
├── triggers/ # 외부 트리거
│ ├── queue/
│ └── processed/
├── logs/ci/ # CI 로그
├── backups/ # 상태 백업
└── references/ # 조사/레퍼런스 저장
├── _index.json # 검색 인덱스
├── research/ # 조사 결과
├── architecture/ # 아키텍처 패턴
├── apis/ # API 문서
└── best-practices/ # 베스트 프랙티스
| 목적 | 경로 |
|---|---|
| Rust 진입점 | minky-rust/src/main.rs |
| Rust 모델 정의 | minky-rust/src/models/ |
| Rust API 라우트 | minky-rust/src/routes/ |
| Rust 서비스 로직 | minky-rust/src/services/ |
| React 컴포넌트 | frontend/src/components/ |
| React API 호출 | frontend/src/services/api.js |
1. 모델 정의 → minky-rust/src/models/{feature}.rs
2. 서비스 구현 → minky-rust/src/services/{feature}_service.rs
3. 라우트 추가 → minky-rust/src/routes/{feature}.rs
4. mod.rs 등록 → 각 디렉토리의 mod.rs에 추가
5. 프론트엔드 → frontend/src/components/{Feature}/
-
Document Ingestion Pipeline
- Markdown 파일 업로드/임포트
- 메타데이터 추출 (제목, 날짜, 출처)
- 청크 분할 (semantic chunking)
-
AI Document Analysis
- Claude로 문서 분석
- 핵심 주제 3-5개 추출
- 해결한 문제/인사이트 식별
- 관련 기술/도구 자동 태깅
-
Vector Embedding Storage
- pgvector 설정
- 문서 임베딩 생성 및 저장
- 청크별 임베딩
-
RAG Search API
- 자연어 질문 → 벡터 검색
- 컨텍스트 조합
- Claude 답변 생성
- 출처 문서 링크
-
Chat Interface
- 대화형 UI
- 스트리밍 응답
- 대화 히스토리
- Auto-linking
- 관련 문서 자동 연결
- 지식 그래프 시각화
- "이것도 볼만해요" 추천
- Conversation Mining (Future)
- Slack/Teams 연동
- 대화에서 지식 추출
- 확인 후 자동 저장
# Document Pipeline
POST /api/documents/ingest # 문서 업로드 + AI 분석
GET /api/documents/{id} # 문서 조회 (분석 결과 포함)
GET /api/documents/{id}/related # 관련 문서
# Knowledge Search (RAG)
POST /api/search/ask # 자연어 질문 → AI 답변
POST /api/search/semantic # 벡터 유사도 검색
GET /api/search/history # 검색 히스토리
# Chat
POST /api/chat/message # 대화 메시지
GET /api/chat/sessions # 대화 세션 목록
WS /api/chat/stream # 스트리밍 WebSocket
/// AI가 분석한 문서 이해 결과
pub struct DocumentUnderstanding {
pub document_id: Uuid,
/// 핵심 주제 (3-5개)
pub topics: Vec<String>,
/// 한줄 요약
pub summary: String,
/// 해결한 문제 (있다면)
pub problem_solved: Option<String>,
/// 핵심 인사이트
pub insights: Vec<String>,
/// 관련 기술/도구
pub technologies: Vec<String>,
/// 누가 알면 좋을까? (역할 기반)
pub relevant_for: Vec<String>,
/// 관련 문서 ID
pub related_documents: Vec<Uuid>,
/// 분석 일시
pub analyzed_at: DateTime<Utc>,
}변경 후 반드시 개발 서버로 테스트하여 에러 확인
.history/YYYY-MM-DD_task_description.md 형식으로 작업 로그 저장
feat: 새 기능
fix: 버그 수정
refactor: 리팩토링
docs: 문서
test: 테스트
- Rust:
cargo clippy통과 - Frontend:
eslint+prettier - 테스트 커버리지 80% 목표
- 사용자가 태그 고민할 필요 없음
- AI가 문맥을 이해하고 자동 연결
- 검색은 자연어로
- 민감한 팀 지식은 로컬 우선
- Vector DB는 self-hosted 가능
- 외부 AI API 호출만 네트워크 필요
- Phase 1만으로도 사용 가능
- 각 Phase가 독립적 가치 제공
- 팀 상황에 맞게 확장
- 검색 성공률: 질문에 관련 답변 찾는 비율
- 지식 재사용률: 저장된 지식이 실제 활용되는 비율
- 암묵지 전환율: 대화/경험 → 문서화된 지식
- 팀원 성장: 다른 팀원 지식으로 문제 해결한 사례
- pgvector PostgreSQL 설정
- Document Understanding 파이프라인 구현
- 벡터 임베딩 저장/검색 API
- RAG 기반 자연어 검색
- 대화형 인터페이스
| 파일 | 내용 |
|---|---|
_index.json |
레퍼런스 검색 인덱스 |
research/2026-02-18_pkm-tools.md |
PKM 도구 비교 조사 |
architecture/rag-patterns.md |
RAG 아키텍처 패턴 |
apis/embedding-apis.md |
Embedding API 비교 |
활용: /ref-search 커맨드로 검색, /ref-save로 새 레퍼런스 저장