sharpdeveye/maestro

1가지 핵심 기술 · 25가지 명령어 · 7가지 도메인 참조 · 메모리 레이어 (memory layer) · 감사 추적 (audit trail)

빠른 시작 (Quick Start) · 명령어 (Commands) · v2 신규 기능 (What's New in v2) · 지원 도구 (Supported Tools) · 기여하기 (Contributing)

AI 에이전트 (AI agents)의 성능은 그들이 작동하는 워크플로 (workflows)의 수준에 달려 있습니다. 가이드가 없다면, 구조화되지 않은 프롬프트 (unstructured prompts), 컨텍스트 윈도우 (context window) 초과, 도구 확산 (tool sprawl), 에러 핸들링 (error handling) 부재, 그리고 단일 에이전트 문제에 멀티 에이전트 시스템 (multi-agent systems)을 사용하는 것과 같이 예측 가능한 동일한 실수들을 반복하게 됩니다.

Maestro는 다음과 같은 방식으로 해당 패턴에 대응합니다:

• 7가지 도메인 특화 참조 파일 (소스 보기)을 포함한 포괄적인 에이전트-워크플로 (agent-workflow) 기술
• 진단, 평가, 개선, 간소화, 강화, 캡처, 성찰 등을 수행하는 25가지 명령어 (25 commands)
• 지속성 메모리 (Persistent memory) — 결정 사항, 감사 추적 (audit trail), 세션 기록이 세션 간에 유지됨
• AI가 무엇을 하지 말아야 하는지 명시적으로 알려주는 큐레이션된 안티 패턴 (anti-patterns)
• 모든 명령어가 프로젝트 특화 인지 능력을 갖추도록 보장하는 컨텍스트 수집 프로토콜 (context gathering protocol) (.maestro.md 또는 .maestro/context.md)
• 모든 명령어는 다음 단계를 권장 — 막다른 길(dead ends)이 없음

npx skills add sharpdeveye/maestro

그 다음, AI 코딩 에이전트 (AI coding agent)에서 원하는 명령어를 사용하세요:

/diagnose # 워크플로 문제 찾기
/streamline # 불필요한 복잡성 제거
/fortify # 에러 핸들링 추가
...

대부분의 명령어는 특정 영역에 집중하기 위한 선택적 인자 (optional argument)를 허용합니다:

/diagnose prompts
/fortify payment-workflow
/specialize legal

/diagnose /calibrate /refine # 전체 워크플로: 감사(audit) → 표준화(standardize) → 다듬기(polish)
/evaluate /fortify /accelerate # 검토(Review) → 강화(harden) → 최적화(optimize)

7가지 도메인 참조를 포함한 포괄적인 워크플로 설계 기술 (기술 보기):

참조 (Reference)	도메인 (Domain)
prompt-engineering	프롬프트 구조 (Prompt structure), 퓨샷 (few-shot), CoT, 출력 스키마 (output schemas)
...
명령어 (Command)	목적 (Purpose)
---	---
/diagnose	점수화된 차원을 통한 체계적인 워크플로 품질 감사 (audit)
/evaluate	워크플로 상호작용 품질에 대한 총체적 검토 (holistic review)
/reflect	🆕 명령어 이력 분석 — 어떤 기술이 작동하고 어떤 것이 실패하는지 분석

명령어	목적
/refine	프롬프트(prompts), 도구(tools), 설정(configuration)에 대한 최종 품질 검토
/streamline	불필요한 복잡성 제거 및 과잉 설계(over-engineering) 평탄화
/calibrate	워크플로우 구성 요소를 프로젝트 관례(conventions)에 맞게 조정
/fortify	오류 처리(error handling), 재시도(retries), 폴백(fallbacks), 서킷 브레이커(circuit breakers) 추가
/zero-defect	최대 정밀도 모드 활성화 — 실수가 허용되지 않는 상태

명령어	목적
/amplify	더 나은 도구와 컨텍스트(context)를 통해 역량 강화
/compose	멀티 에이전트 오케스트레이션(multi-agent orchestration) 및 위임(delegation) 설계
/enrich	지식 소스, RAG, 그라운딩(grounding) 추가
/accelerate	속도 최적화, 지연 시간(latency) 및 비용 감소
/chain	효과적인 도구 체인(tool chains) 및 파이프라인(pipelines) 구축
/guard	안전 제약 조건 및 보안 경계 추가
/iterate	피드백 루프(feedback loops) 및 평가 주기(evaluation cycles) 설정
/temper	과잉 설계 감소 및 과하게 구축된 워크플로우 단순화
/turbocharge	기존의 한계를 돌파 — 고급 기술 적용

명령어	목적
/extract-pattern	작동하는 워크플로우에서 재사용 가능한 패턴 추출
/adapt-workflow	다양한 제공자(providers) 및 컨텍스트에 맞게 워크플로우 조정
/onboard-agent	처음부터 새로운 에이전트 설정 구축
/specialize	워크플로우를 특정 도메인(법률, 의료 등)에 특화
/teach-maestro	일회성 컨텍스트 수집, .maestro.md에 저장
/capture	🆕 세션 요약 저장 — 발생한 내용을 유지
/recap	🆕 마지막 세션의 빠른 요약

이제 Maestro는 세션 전반에 걸쳐 발생한 일을 기억합니다:

.maestro/
├── context.md ← 프로젝트 컨텍스트 ( .maestro.md 를 대체함)
├── decisions.jsonl ← 추가 전용(append-only) 결정 로그
...

하위 호환성 유지 (Backward compatible) — .maestro.md를 사용하는 사용자는 변경할 것이 없습니다.

선택적 적용 (Opt-in) — .maestro/는 /capture를 실행하거나 확장을 사용할 때만 생성됩니다.

Git 친화적 (Git-friendly) — 세션 데이터는 기본적으로 gitignored 처리되며, 컨텍스트 파일은 버전 관리됩니다.

모든 명령어 호출은 소요 시간, 토큰 사용량 및 예상 비용과 함께 기록됩니다:

{"command":"fortify","duration_ms":8200,"cost_estimate_usd":0.019,"exit_status":"completed"}

Claude, GPT-4, Gemini 등을 위한 대략적인 비용 추적입니다. 정확도: ±20% — 추세를 파악하는 데 유용하며, 청구용(invoicing)으로는 적합하지 않습니다.

명령어 기록을 분석하여 어떤 기술(skill)이 작동하고, 어떤 것이 실패하며, 어디를 개선해야 하는지 확인하세요:

╔══════════════════════════════════════════╗
║ MAESTRO EFFECTIVENESS ║
╠══════════════════════════════════════════╣
...

해당 기술에는 피해야 할 사항에 대한 명시적인 가이드가 포함되어 있습니다:

• 전체 코드베이스나 데이터베이스를 컨텍스트(context)에 한꺼번에 쏟아붓지 마세요
• 단일 에이전트(single-agent) 문제에 멀티 에이전트(multi-agent) 시스템을 사용하지 마세요
• 에러 핸들링(error handling)을 생략하지 마세요 (해피 패스(happy path)만 고려하는 것은 운영 환경에서의 실패를 의미합니다)
• 다른 결과를 기대하며 동일한 프롬프트(prompt)를 재시도하지 마세요
• 비용 제어(cost controls) 없이 배포하지 마세요
• 모델을 혼란스럽게 하는 모호한 도구(tool) 설명을 사용하지 마세요
• 평가(evaluation) 없이 출시하지 마세요 ("작동하는 것 같다" ≠ 테스트 완료)

도구 (Tool)	디렉토리 (Directory)
Cursor	.cursor/skills/
...

정적인 기술 파일 대신 Maestro를 라이브 MCP 서버로 사용하세요. MCP 호환 클라이언트라면 무엇이든 연결할 수 있으며, 파일을 복사할 필요가 없습니다.

MCP 클라이언트 설정(Claude Desktop, Cursor, VS Code 등)에 추가하세요:

{
"mcpServers": {
"maestro": {
...

Maestro를 공개 MCP 엔드포인트(endpoint)로 호스팅하세요:

npx maestro-workflow-mcp --http --port 3001

클라이언트는 http://your-server:3001/mcp로 연결합니다.

.

유형 (Type)	개수 (Count)	설명 (Description)
프롬프트 (Prompts)	25	명령어당 하나 — 프롬프트 선택기(prompt picker)에서 선택
도구 (Tools)	10	list_commands , run_command , read_context , init , wave_start , wave_advance , wave_status , write_decision , read_decisions , read_audit
리소스 (Resources)	8	핵심 기술(Core skill) + 7개의 도메인 참조

사용자의 환경에서 npx skills add가 작동하지 않는 경우, 적절한 프로바이더(provider) 디렉토리를 프로젝트 루트로 복사하세요:

# Claude Code 예시
cp -r .claude/skills/ your-project/.claude/skills/
# Cursor 예시
...

maestro/
├── source/skills/ # 25개의 소스 스킬 정의 (source skill definitions)
│ ├── agent-workflow/ # 핵심 스킬 (Core skill) + 7개의 참조 파일 (reference files)
...

기여(Contributions)를 환영합니다! 다음 사항을 반드시 준수해 주세요:

• 모든 콘텐츠는 독창적이어야 합니다 (다른 스킬 프로젝트에서 복사 금지)
• SKILL.md 파일은 "Use when..."으로 시작하는 description을 포함한 유효한 YAML 프론트매터 (YAML frontmatter)를 가져야 합니다.
• 모든 코드 펜스 (code fences)에는 언어 지정자 (language specifier)가 있어야 합니다.
• 제출 전 npm run check를 실행하여 유효성을 검사하세요.

MIT — LICENSE를 참조하세요.