--- name: "moai-alfred-rules" version: "4.0.0" created: 2025-11-02 updated: 2025-11-12 status: stable tier: Alfred description: "Alfred SuperAgent의 필수 규칙을 정의합니다. November 2025 enterprise standard 기반. 3-Layer architecture, 4-Step workflow, Agent-first paradigm, Skill invocation rules, AskUserQuestion patterns, TRUST 5 quality gates, TAG chain integrity, commit message standards. 사용: 워크플로우 규칙 검증, 품질 게이트 확인, MoAI-ADK 표준 준수, 아키텍처 규칙 검증." keywords: ['rules', 'agent-first', 'skill-invocation', 'ask-user-question', 'trust-5', 'tag-chain', 'workflow-compliance', 'quality-gates', '4-step-workflow', 'architecture-rules'] allowed-tools: "Read, Glob, Grep, Bash, AskUserQuestion, TodoWrite" --- ## Skill 개요 **moai-alfred-rules**는 Alfred SuperAgent의 의사결정과 실행을 제어하는 핵심 프레임워크입니다. | 항목 | 값 | |------|-----| | 버전 | 4.0.0 (November 2025 enterprise) | | 티어 | Alfred (상위 계층) | | 자동 로드 | 규칙 검증, 품질 게이트, 아키텍처 규칙 필요 시 | | 아키텍처 패러다임 | Agent-First (Command → Agent → Skill → Hook) | | 워크플로우 모델 | 4-Step ADAP Workflow | --- ## 무엇을 하는가? ### 핵심 책임 1. **3-Layer Architecture 정의**: Commands → Agents → Skills 계층 분리 2. **4-Step Workflow 규칙**: ADAP (Analyze, Design, Assure, Produce) + Intent 3. **Agent-First Paradigm**: 모든 실행 작업을 agents에 위임 4. **Skill 호출 규칙**: 10+ mandatory patterns, invocation syntax 5. **AskUserQuestion 패턴**: 5가지 필수 사용 시나리오 6. **TRUST 5 Quality Gates**: T/R/U/S/T 각각의 검증 기준 7. **TAG Chain Integrity**: SPEC→TEST→CODE→DOC 추적 8. **Commit Message Standards**: TDD cycle message formats --- ## 언제 사용하는가? ### 필수 시나리오 (MUST use) | 상황 | 사용 여부 | |------|---------| | ✅ Skill() 호출 규칙 검증 | **필수** | | ✅ Command vs Agent 역할 분리 | **필수** | | ✅ AskUserQuestion 사용 판단 | **필수** | | ✅ TRUST 5 준수 확인 | **필수** | | ✅ TAG 체인 무결성 검증 | **필수** | | ✅ 커밋 메시지 형식 확인 | **필수** | | ✅ 워크플로우 compliance 검증 | **필수** | | ✅ Agent delegation 올바른지 확인 | **필수** | | ✅ 품질 게이트(quality gate) 통과 | **필수** | | ✅ 아키텍처 규칙 위반 감지 | **필수** | --- ## Rule 1: 3-Layer Architecture (November 2025 Standard) ### 계층 구조 ``` ┌─────────────────────────────────────┐ │ Commands (Orchestration Only) │ ← User-facing entry points │ /alfred:0-project, /alfred:1-plan │ No direct execution │ /alfred:2-run, /alfred:3-sync │ └──────────┬──────────────────────────┘ │ Task(subagent_type="...") ↓ ┌─────────────────────────────────────┐ │ Agents (Domain Expertise) │ ← Deep reasoning │ spec-builder, tdd-implementer │ Complex decisions │ test-engineer, doc-syncer │ Plan → Execute │ git-manager, qa-validator │ └──────────┬──────────────────────────┘ │ Skill("skill-name") ↓ ┌─────────────────────────────────────┐ │ Skills (Knowledge Capsules) │ ← Reusable patterns │ 55 specialized Skills │ Playbooks │ < 1000 lines each │ Best practices └─────────────────────────────────────┘ ``` ### 규칙 1.1: Commands - Orchestration ONLY **금지 사항 (❌)**: ```bash # ❌ WRONG: 직접 작업 실행 echo "Building application..." python setup.py build git commit -m "Build" # ❌ WRONG: Skill 직접 호출 Skill("moai-alfred-rules") # Commands에서 금지! # ❌ WRONG: 복잡한 로직 구현 if feature_type == "backend": # 복잡한 비즈니스 로직... ``` **필수 사항 (✅)**: ```bash # ✅ CORRECT: Agent에 위임 Task( subagent_type="tdd-implementer", description="Build and test application", prompt="Implement feature with RED-GREEN-REFACTOR cycle" ) # ✅ CORRECT: 의사결정만 하고 위임 if user_approval_needed: AskUserQuestion(...) # 사용자 확인 후 위임 Task(subagent_type="implementation-planner", ...) ``` ### 규칙 1.2: Agents - Domain Expertise Ownership **agent의 책임**: - ✅ 복잡한 분석 & 추론 (deep reasoning) - ✅ 계획 수립 (planning) - ✅ 의사결정 (decision-making) - ✅ Skill 호출 및 조율 (orchestration within domain) - ✅ 작업 실행 (execution) **예시: tdd-implementer Agent**: ``` Agent receives: "Implement user authentication" ↓ 1. Analyze: SPEC 검토, 요구사항 분석 2. Design: 아키텍처 설계 3. RED: test-engineer Skill 호출 → 테스트 작성 4. GREEN: 코드 구현 5. REFACTOR: 최적화 6. Commit: git-manager 호출 → commit ↓ Returns: Fully tested, documented, committed code ``` ### 규칙 1.3: Skills - Knowledge Capsules (Stateless) **Skill 특성**: - ✅ 상태가 없음 (stateless) - ✅ 재사용 가능 (reusable) - ✅ Agent에 의해 호출됨 (called by agents) - ✅ 1000줄 이하 (< 1000 lines) - ✅ 단일 주제 (single topic) **금지 (❌)**: ```bash # ❌ WRONG: Skill이 다른 Skill 호출 Skill("moai-foundation-git") # ← Skills에서 금지! # ❌ WRONG: Skill이 Task() 실행 Task(subagent_type="...") # ← Skills에서 금지! # ❌ WRONG: Skill이 상태 유지 state = {"counter": 0} # ← Stateless 위반 ``` --- ## Rule 2: 4-Step Agent-Based Workflow (November 2025) ### Phase Overview ``` Phase 0: INTENT Phase 1: ANALYZE ┌──────────────────┐ ┌──────────────────┐ │ User Request │ ─clarity?─→ │ WebSearch │ │ Ambiguous? │ NO │ WebFetch │ │ ✅ YES: clarify │ YES │ Research │ │ ✅ NO: continue │────────────→ │ Best practices │ └──────────────────┘ └──────────────────┘ ↓ Phase 3: ASSURE Phase 2: DESIGN ┌──────────────────┐ ┌──────────────────┐ │ Quality Gate │←──────────────→│ Architecture │ │ TRUST 5 │ │ Latest info │ │ TAG integrity │ │ Version specs │ │ Compliance │ │ Design patterns │ └──────────────────┘ └──────────────────┘ ↓ Phase 4: PRODUCE ┌──────────────────┐ │ Skill invocation │ │ File generation │ │ Commit │ └──────────────────┘ ``` ### Phase 0: Intent (사용자 의도 파악) **규칙 0.1**: Intent가 모호하면 AskUserQuestion 사용 ``` 상황: "데이터 처리 모듈 만들어줘" Step 1: Intent 평가 ├─ Clarity: LOW (어떤 데이터? 어떤 처리?) └─ Action: AskUserQuestion 사용 Step 2: 명확화 AskUserQuestion({ question: "어떤 데이터를 처리하나요?", options: [ "CSV 파일", "데이터베이스", "API 응답" ] }) Step 3: 명확한 요구사항 확보 후 다음 phase로 ``` ### Phase 1: Analyze (정보 수집 & 연구) **도구**: WebSearch, WebFetch ``` Task 1: Research latest information ├─ Search: "[framework] [version] best practices 2025" ├─ Fetch: Official documentation URLs └─ Validate: Cross-check multiple sources Task 2: Collect best practices ├─ Official docs ├─ Industry standards └─ Current patterns (2025) Task 3: Identify version-specific guidance ├─ Current stable version ├─ Breaking changes └─ Deprecation warnings ``` ### Phase 2: Design (아키텍처 설계) **입력**: Phase 1의 연구 결과 **출력**: November 2025 최신 정보를 기반한 설계 ``` Design Activities: ├─ 최신 정보 기반 이름 지정 ├─ 현재 버전 명시 ├─ 최신 패턴 포함 ├─ 공식 문서 링크 └─ 마지막 업데이트 날짜 포함 ``` ### Phase 3: Assure (품질 검증) **TRUST 5 Quality Gates**: | Gate | 검증 기준 | |------|----------| | **Test** | 85%+ coverage, 모든 경로 테스트 | | **Readable** | Clean code, SOLID 원칙, 주석 포함 | | **Unified** | 일관된 패턴, 중복 제거, 네이밍 표준 | | **Secured** | OWASP Top 10 확인, 비밀정보 제거 | ### Phase 4: Produce (생성 & 배포) **책임**: Skill 호출 (예: moai-skill-factory) ``` Actions: ├─ 템플릿 적용 ├─ 파일 생성 ├─ 메타데이터 추가 ├─ 최신 정보 embedded ├─ 공식 문서 링크 포함 └─ Version date 표기 ``` --- ## Rule 3: Agent-First Paradigm (Critical Enforcement) ### 금지된 작업 (❌ ABSOLUTELY FORBIDDEN) Alfred (또는 Command)가 직접 실행하면 **절대** 안 됩니다: 1. **직접 bash 명령 실행** ❌ ```bash # ❌ WRONG bash("git commit -m 'message'") os.system("python build.py") # ✅ CORRECT Task(subagent_type="git-manager", prompt="Commit changes") ``` 2. **파일 읽기/쓰기** ❌ ```bash # ❌ WRONG with open("file.py", "w") as f: f.write(code) # ✅ CORRECT Task(subagent_type="file-manager", prompt="Create file") ``` 3. **Git 직접 조작** ❌ ```bash # ❌ WRONG subprocess.run(["git", "push", "origin", "main"]) # ✅ CORRECT Task(subagent_type="git-manager", prompt="Push changes") ``` 4. **코드 분석 직접 실행** ❌ ```bash # ❌ WRONG lines = len(open("file.py").readlines()) # ✅ CORRECT Task(subagent_type="code-analyzer", prompt="Analyze code") ``` 5. **테스트 직접 실행** ❌ ```bash # ❌ WRONG subprocess.run(["pytest", "tests/"]) # ✅ CORRECT Task(subagent_type="test-engineer", prompt="Run tests") ``` ### 의무 위임 (✅ MANDATORY DELEGATION) | 작업 | 위임 대상 | 패턴 | |------|---------|------| | 계획 수립 | plan-agent | `Task(subagent_type="plan-agent", ...)` | | 코드 개발 | tdd-implementer | `Task(subagent_type="tdd-implementer", ...)` | | 테스트 작성 | test-engineer | `Task(subagent_type="test-engineer", ...)` | | 문서화 | doc-syncer | `Task(subagent_type="doc-syncer", ...)` | | Git 작업 | git-manager | `Task(subagent_type="git-manager", ...)` | | 품질 검증 | qa-validator | `Task(subagent_type="qa-validator", ...)` | | 사용자 질문 | ask-user-questions | `AskUserQuestion(...)` | --- ## Rule 4: 10 Mandatory Skill Invocations ### 규칙 4.1: Skill Invocation Pattern **Syntax**: ```python Skill("skill-name") # Explicit invocation only ``` ### 10가지 필수 Skill | # | Skill | 용도 | Invocation | |---|-------|------|-----------| | 1 | moai-foundation-trust | TRUST 5 검증 | `Skill("moai-foundation-trust")` | | 2 | moai-foundation-tags | TAG 검증 & 추적 | `Skill("moai-foundation-tags")` | | 3 | moai-foundation-specs | SPEC 작성 & 검증 | `Skill("moai-foundation-specs")` | | 4 | moai-foundation-ears | EARS 요구사항 형식 | `Skill("moai-foundation-ears")` | | 5 | moai-foundation-git | Git 워크플로우 | `Skill("moai-foundation-git")` | | 6 | moai-foundation-langs | 언어 & 스택 감지 | `Skill("moai-foundation-langs")` | | 7 | moai-essentials-debug | 디버깅 & 에러 분석 | `Skill("moai-essentials-debug")` | | 8 | moai-essentials-refactor | 리팩토링 & 개선 | `Skill("moai-essentials-refactor")` | | 9 | moai-essentials-perf | 성능 최적화 | `Skill("moai-essentials-perf")` | | 10 | moai-essentials-review | 코드 리뷰 & 품질 | `Skill("moai-essentials-review")` | ### 규칙 4.2: Skill Invocation 예제 ```python # Context 1: TRUST 5 검증 필요 if validation_required: Skill("moai-foundation-trust") # → 반환: TRUST score, violations, recommendations # Context 2: TAG 체인 검증 if tag_integrity_check: Skill("moai-foundation-tags") # → 반환: 고아 TAG, 깨진 체인, 제안 # Context 3: SPEC 작성 if spec_needed: Skill("moai-foundation-specs") # → 반환: SPEC template, validation results # Context 4: Git 워크플로우 if git_decision_needed: Skill("moai-foundation-git") # → 반환: branch strategy, commit format, merge rules ``` --- ## Rule 5: AskUserQuestion Patterns (5가지 필수 시나리오) ### 규칙 5.1: MANDATORY Scenarios **Scenario 1: 기술 스택 모호** ``` 상황: "Python 웹 프레임워크 추천해줄래?" AskUserQuestion({ question: "어떤 유형의 애플리케이션?", header: "Application Type", options: [ { label: "REST API", description: "High performance APIs" }, { label: "Web Application", description: "Traditional MVC" }, { label: "Microservice", description: "Event-driven" } ] }) ``` **Scenario 2: 아키텍처 결정** ``` 상황: "데이터베이스 모델을 어떻게 설계?" AskUserQuestion({ question: "어떤 데이터 특성?", header: "Data Model", options: [ { label: "Relational", description: "Structured, ACID" }, { label: "Document", description: "Flexible schema" }, { label: "Graph", description: "Relationships" } ] }) ``` **Scenario 3: 의도 모호** ``` 상황: "코드 개선해줄래?" AskUserQuestion({ question: "어떤 측면을 개선?", header: "Improvement Focus", options: [ { label: "Performance", description: "Speed & efficiency" }, { label: "Readability", description: "Code clarity" }, { label: "Security", description: "Vulnerability fixes" } ], multiSelect: true # 복수 선택 허용 }) ``` **Scenario 4: 기존 컴포넌트 영향** ``` 상황: "패키지 업그레이드하려는데 호환성?" AskUserQuestion({ question: "기존 코드 호환성 유지 필요?", header: "Compatibility", options: [ { label: "Full compatibility", description: "Maintain all APIs" }, { label: "Deprecation path", description: "Gradual migration" }, { label: "Breaking OK", description: "Version bump allowed" } ] }) ``` **Scenario 5: 자원 제약** ``` 상황: "시스템 리팩토링 계획 수립" AskUserQuestion({ question: "예상 개발 기간?", header: "Timeline", options: [ { label: "1 week", description: "Focused scope" }, { label: "2-4 weeks", description: "Medium refactor" }, { label: "1+ months", description: "Comprehensive" } ] }) ``` ### 규칙 5.2: 올바른 사용법 **❌ WRONG** (평문 질문): ``` 사용자: "뭘 선호해?" 응답: "음... 생각해봤는데 아마도..." ``` **✅ CORRECT** (AskUserQuestion): ``` AskUserQuestion({ question: "어떤 접근을 선호하시나요?", header: "Approach", multiSelect: false, options: [ { label: "Option A", description: "Benefit A, Cost B" }, { label: "Option B", description: "Benefit C, Cost D" } ] }) ``` --- ## Rule 6: TRUST 5 Quality Gates (November 2025 Enterprise) ### 각 Gate의 검증 기준 #### T: Test First (85%+ Coverage) ```yaml requirements: coverage: "≥ 85%" coverage_tools: ["pytest-cov", "coverage.py"] test_types: - unit_tests: "각 함수/메서드" - integration_tests: "모듈 간 상호작용" - edge_cases: "경계값, 에러 처리" validation: - All code paths executed - Error conditions tested - Mock external dependencies - No skipped tests (×skip, ×xfail) ``` #### R: Readable (Clean Code) ```yaml requirements: code_standards: - SOLID 원칙 준수 - DRY (Don't Repeat Yourself) - KISS (Keep It Simple, Stupid) documentation: - Function docstrings - Complex logic comments - Type hints (Python 3.10+) naming: - Descriptive variable names - Consistent conventions - No single-letter vars (except i, j, k in loops) ``` #### U: Unified (Consistent Patterns) ```yaml requirements: consistency: - Same patterns across codebase - No duplicate logic - Shared utilities for common tasks conventions: - Consistent indentation (4 spaces) - Consistent naming (snake_case, PascalCase) - Consistent import order validation: - Linting (flake8, black, isort) - Static analysis (pylint, mypy) - No code duplication (DRY violations) ``` #### S: Secured (OWASP Top 10) ```yaml requirements: security_checks: - No hardcoded credentials - No SQL injection vectors - No XXE vulnerabilities - Input validation - Output encoding tools: - bandit (Python security linter) - safety (dependency vulnerabilities) - SAST scanning validation: - No secrets committed - Dependencies scanned - Known CVEs checked ``` ```yaml requirements: tag_chain: - Complete history traceability documentation: validation: - Bidirectional references ``` --- ## Rule 7: TAG Chain Integrity Rules ### 규칙 7.1: TAG Naming Convention ``` Format: @-<###> Examples: ``` ### 규칙 7.2: TAG Lifecycle ``` └─ Example: test_auth.py - test_auth_success() └─ Example: auth.py - authenticate_user() └─ Example: CHANGELOG.md ``` ### 규칙 7.3: TAG Validation Rules **❌ 위반**: ```python # 1. Orphan TAG (TEST/CODE 없음) # 2. 깨진 체인 (missing step) # 3. 불일치 (다른 번호) ``` **✅ 정확**: ```python # Complete chain ``` --- ## Rule 8: Commit Message Standards (TDD Cycle) ### 규칙 8.1: Commit Format ``` Format: ():