에이전트 지침서 심층 검토 리포트 (2026-05-02)

검토 범위:

• .claude/plugins/phase-orchestrator/PLUGIN.md
• .claude/plugins/content-creation/PLUGIN.md
• .claude/plugins/aplus-development/PLUGIN.md
• 각 플러그인의 하위 에이전트/스킬/서브플러그인 파일 중 실제로 존재하는 파일

전제:

• 모든 평가는 실제 파일 문구를 근거로 했다.
• 파일이 없어서 세부 검토가 불가능한 항목은 MISSING으로 표기했다.
• 추정이 필요한 경우에만 (가정)으로 명시했다.

1. 강점 분석

• phase-orchestrator는 역할 분리가 가장 명확하다. project-manager는 전략 결정, milestone-tracker는 일정 추적, risk-assessor는 위험 분석으로 입력/출력이 구분되어 있다 (PLUGIN.md, project-manager.md, milestone-tracker.md, risk-assessor.md).
• phase-orchestrator의 스킬 구성이 운영 루프를 잘 닫는다. 마일스톤 정의, KPI 추적, 발행 캘린더, 레드팀 재검증이 각각 분리되어 있어 Phase 운영 문서로서 완결성이 높다 (phase-milestone-tracking.md, blog-pilot-metrics.md, content-calendar.md, redteam-closure.md).
• 모델 배정은 phase-orchestrator 내부에서는 합리적이다. 빠른 추적은 Haiku, 분석은 Sonnet, 전략 판단은 Opus로 배정했고 명령별 기대 응답 시간까지 문서화했다 (milestone-tracker.md, risk-assessor.md, project-manager.md, commands/README.md).
• content-creation은 초안 생성, 검수, SNS 확장으로 콘텐츠 생산 흐름이 단계화되어 있다. 특히 blog-content-expert는 출력 frontmatter와 SEO 메타 형식을 명시하고, editor-reviewer는 점검 항목과 우선순위 피드백을 구조화해 실무 지침서로 바로 사용 가능하다 (PLUGIN.md, blog-content-expert.md, blog-content-expert.md, editor-reviewer.md, editor-reviewer.md).
• content-creation의 도메인 적합성은 높다. elementary-pedagogy, parent-communication, seasonal-marketing, naver-blog-formatting은 kids-academy-vault의 블로그/학부모 커뮤니케이션 목적과 직접 맞닿아 있다 (PLUGIN.md, seasonal-marketing.md, parent-communication.md, naver-blog-formatting.md).
• aplus-development는 상위 구조 설계 자체는 좋다. 기능개발, QA, DevOps, Data Ops를 서브플러그인으로 나눈 계층 구조는 실제 제품 개발 조직 구조와 맞고, aplus-feature-team은 백엔드/프런트/통합 검증을 분리해 병렬 개발 구조를 구체화했다 (PLUGIN.md, aplus-feature-team/PLUGIN.md, fullstack-architect.md).

2. 약점/위험 분석

• [심각도: 높음] aplus-development는 선언 대비 실제 구현 문서가 많이 비어 있다. 상위 플러그인은 test-engineer, security-auditor, code-reviewer, deployment-engineer, infrastructure-engineer, monitoring-engineer, database-architect, data-engineer와 다수 스킬을 전제하지만, 현재 워크스페이스에서는 개별 에이전트 파일과 스킬 파일을 확인할 수 없었다 (PLUGIN.md, PLUGIN.md, PLUGIN.md). 실행성 면에서 가장 큰 리스크다.
• [심각도: 높음] phase-orchestrator의 명령 소유권이 일부 충돌한다. commands/README.md에서 /phase:status는 “project-manager 실행”으로 설명되지만, 같은 문서의 응답 시간 표에서는 milestone-tracker | Haiku로 매핑된다 (commands/README.md, commands/README.md). 동일 명령에 대한 실행 주체가 둘이면 운영 혼선이 생긴다.
• [심각도: 높음] content-creation은 핵심 병렬 워크플로에서 외부 의존을 강하게 전제한다. 다이어그램에는 parent-behavior-analyst, student-psychologist, deployment-engineer가 필수 단계처럼 들어가지만, 이 플러그인 내부에는 그 정의가 없다 (PLUGIN.md, PLUGIN.md, blog-content-expert.md, editor-reviewer.md). 지금 상태에서는 문서상 병렬화가 실제로는 외부 플러그인 가용성에 종속된다.
• [심각도: 중간] phase-orchestrator에는 순환 참조가 있다. project-manager는 milestone-tracker와 risk-assessor를 연결 에이전트로 두고, milestone-tracker와 risk-assessor도 다시 project-manager를 연결 대상으로 둔다 (project-manager.md, milestone-tracker.md, risk-assessor.md). 협업 구조 자체는 자연스럽지만, 호출 규칙이 없으면 상호 재호출 루프 위험이 있다.
• [심각도: 중간] Opus 사용량이 과한 편이다. content-creation의 blog-content-expert, aplus-development의 backend-engineer, frontend-engineer, security-auditor, database-architect가 모두 Opus다 (PLUGIN.md, PLUGIN.md, PLUGIN.md, PLUGIN.md). 문서 내용을 보면 템플릿·체크리스트·예시 위주인 부분이 많아 상시 Opus가 꼭 필요한지는 약하다.
• [심각도: 중간] content-creation의 병렬 처리 설계는 버전 관리와 병합 책임이 불명확하다. 초안 작성 중 심리 검증을 병렬로 수행한다고 되어 있지만, 어느 버전을 기준으로 여러 에이전트가 검토하는지, 수정 충돌이 생기면 누가 합치는지 명시되지 않았다 (PLUGIN.md, social-media-strategist.md).
• [심각도: 중간] aplus-feature-team은 병렬 구현을 잘 제시하지만 계약 동결 시점이 약하다. backend-engineer가 API를 만들고 frontend-engineer가 동시에 붙는 구조인데, fullstack-architect가 언제 계약을 확정하고 언제 재검증하는지가 명령 수준에서 강제되지 않는다 (aplus-feature-team/PLUGIN.md, fullstack-architect.md).
• [심각도: 낮음] 실패 복구 전략의 완성도가 플러그인마다 다르다. phase-orchestrator는 수동 발행 대체 경로를 언급하고 (content-calendar.md, content-calendar.md), aplus-devops는 프로덕션 배포 전 백업을 언급하지만 (aplus-devops/PLUGIN.md), content-creation은 리뷰 실패나 SNS 생성 실패 시 재시도/우회 정책이 약하다.
• [심각도: 낮음] 저장소 도메인이 혼재한다. kids-academy-vault의 블로그/학부모 도메인과 A+ Tracker 제품 개발 도메인이 같은 플러그인 세트 안에 공존한다. 분리 자체는 가능하지만, 운영 우선순위 조정 장치가 약하면 실행 순서 충돌이 생길 수 있다 (phase-orchestrator/PLUGIN.md, content-creation/PLUGIN.md, aplus-development/PLUGIN.md).

3. 개선 권장사항

• /phase:status의 실행 주체를 하나로 고정하라. 추천은 milestone-tracker를 기본 실행기로 두고, 전략 이슈 감지 시에만 project-manager로 escalate하는 방식이다.
  수정 지점:
  • commands/README.md
  • commands/README.md
• phase-orchestrator에는 호출 규칙을 추가하라.
  예시:

  호출 규칙:
  - milestone-tracker는 상태 갱신만 수행하고 next action은 확정하지 않는다.
  - risk-assessor는 high 리스크일 때만 project-manager에 escalate한다.
  - project-manager만 최종 우선순위를 확정한다.

• content-creation에는 초안 버전 규칙과 병합 책임자를 명시하라.
  예시:

  draft_vN 생성: blog-content-expert
  검수 입력 기준: 모든 검수 에이전트는 동일한 draft_vN만 읽음
  병합 책임: editor-reviewer가 merged_vN+1 작성
  publish gate: social-media-strategist는 final: true 문서만 입력으로 받음

• content-creation의 외부 의존은 optional/fallback 구조로 바꾸는 것이 좋다. 현재처럼 외부 심리 에이전트를 전제하면 가용성에 따라 파이프라인이 깨진다.
  예시:

  optional_reviewers:
  - parent-behavior-analyst
  - student-psychologist
   
  fallback:
  - unavailable 시 editor-reviewer + parent-communication checklist만으로 진행

• aplus-development는 먼저 MISSING 문서를 채워야 한다. 상위 PLUGIN 설계보다 실행 주체 문서의 실체가 우선이다.
  우선 생성 대상:
  • subplugins/aplus-qa-team/agents/*.md
  • subplugins/aplus-devops/agents/*.md
  • subplugins/aplus-data-ops/agents/*.md
  • .claude/plugins/aplus-development/skills/*.md
• aplus-feature-team에는 계약 동결 단계를 명령에 넣어라.
  예시:

  /aplus:feature-implement --parallel
  1. backend-engineer가 OpenAPI draft 생성
  2. fullstack-architect가 contract-lock 승인
  3. frontend-engineer 구현 시작
  4. merge 전 fullstack-architect 재검증

• 비용 최적화를 위해 모델 재배치를 검토하라.
  • frontend-engineer: Sonnet 기본, 복잡한 UI 재설계 시만 Opus
  • security-auditor: Sonnet 기본, 고위험 감사만 Opus
  • database-architect: Sonnet 기본, RLS/대규모 스키마 변경 시만 Opus
  • blog-content-expert: 초안 Sonnet, 최종 품질본만 Opus

4. 우선순위 조정

1. aplus-development의 실행 불능 요소부터 해소하라.

• 이유: 현재는 서브플러그인 구조는 좋지만 다수 에이전트/스킬 파일이 없어서 실제 실행이 끊긴다.
• 완료 조건: QA/DevOps/Data Ops의 개별 에이전트 문서와 핵심 스킬 문서 생성.

2. phase-orchestrator의 명령 라우팅과 호출 규칙을 정리하라.

• 이유: 이 플러그인은 가장 운영 가능한 상태이지만, /phase:status 소유권 충돌과 순환 참조를 정리해야 안정적이다.
• 완료 조건: 명령-에이전트 1:1 매핑과 escalate 규칙 명시.

3. content-creation의 외부 의존을 optional/fallback 구조로 바꿔라.

• 이유: 실제 블로그 운영에 가장 직접적으로 쓰일 플러그인인데, 외부 에이전트 미가용 시 병렬 설계가 깨진다.
• 완료 조건: 버전 규칙, fallback reviewer, publish gate 정의.

4. 마지막으로 모델 비용 최적화를 하라.

• 이유: 구조를 먼저 안정화한 뒤 비용을 줄이는 편이 리스크가 작다.
• 완료 조건: Sonnet 기본, Opus escalate 기준 표준화.

5. 테스트 전략

• /phase:status, /phase:milestone-check, /phase:risk-assessment, /phase:next-action가 각각 단일 책임 에이전트로만 라우팅되는지 확인
• project-manager ↔ milestone-tracker ↔ risk-assessor 사이에 무한 재호출이 없는지 시뮬레이션
• content-creation에서 동일 draft_vN 기준으로 review와 SNS 생성이 이뤄지는지 검증
• 외부 심리 에이전트 부재 시 editor-reviewer + parent-communication만으로 발행 가능한지 fallback 테스트
• aplus-feature-team에서 OpenAPI draft 없이 프런트 구현이 먼저 시작되지 않도록 contract-lock 테스트
• aplus-qa-team, aplus-devops, aplus-data-ops의 MISSING 문서 보완 후 각 커맨드 dry-run 검증
• 병렬 작업 충돌 테스트: backend/frontend가 같은 계약 필드를 수정할 때 fullstack-architect가 불일치를 검출하는지 확인
• 실패 복구 테스트:
  • 콘텐츠 발행 실패 시 수동 발행으로 전환되는지
  • staging 배포 실패 시 production 배포가 차단되는지
  • migration 실패 시 복구 절차가 문서에 존재하는지
• 모델 비용 샘플링:
  • 동일 작업을 Opus/Sonnet으로 각각 수행
  • 품질 차이가 상시 Opus 사용을 정당화하는지 비교
• 도메인 적합성 리뷰:
  • kids-academy-vault: 학부모 심리, 시즌성, 네이버 블로그 운영 흐름 반영 여부
  • A+ Tracker: JWT/RLS/멀티서비스/배포/테스트/마이그레이션 흐름 반영 여부

MISSING 항목

• aplus-development가 상위 문서에서 직접 참조하지만 현재 확인되지 않은 개별 에이전트 파일:
  • test-engineer.md
  • security-auditor.md
  • code-reviewer.md
  • deployment-engineer.md
  • infrastructure-engineer.md
  • monitoring-engineer.md
  • database-architect.md
  • data-engineer.md
• aplus-development가 상위 문서에서 직접 참조하지만 현재 확인되지 않은 스킬 파일:
  • fastapi-patterns.md
  • sqlalchemy-orm.md
  • pydantic-validation.md
  • claude-integration.md
  • nextjs-app-router.md
  • react-components.md
  • api-integration.md
  • shadcn-ui-patterns.md
  • pytest-patterns.md
  • jest-testing.md
  • playwright-e2e.md
  • jwt-security.md
  • rls-policies.md
  • owasp-top-10.md

총평

현재 완성도는 phase-orchestrator > content-creation > aplus-development 순이다.

• phase-orchestrator는 가장 운영 가능한 상태다. 다만 명령 라우팅 충돌과 순환 호출 규칙을 먼저 정리해야 한다.
• content-creation은 도메인 적합성이 높고 실제 블로그 운영 지침으로 강하다. 하지만 외부 에이전트 의존을 optional로 바꾸지 않으면 문서 대비 실행성이 떨어진다.
• aplus-development는 아키텍처 방향은 가장 야심차지만, 현재는 선언이 구현을 앞선다. 먼저 MISSING 문서를 채운 뒤 병렬 오케스트레이션을 검증하는 편이 맞다.