diff --git a/planning-contract/SPEC.md b/planning-contract/SPEC.md new file mode 100644 index 0000000..7b9fb36 --- /dev/null +++ b/planning-contract/SPEC.md @@ -0,0 +1,171 @@ +# 계획 계약 명세서 (Planning Contract Specification) + +## 개요 + +MiniMax 기반 에이전트의 계획 계약은 에이전트가 수립한 계획의 품질, 완전성, 실행 가능성을 보장하기 위한 명세서이다. 본 문서는 계약의 각 조항과 그에 대한 검증 기준을 정의한다. + +--- + +## 용어 정의 + +| 용어 | 정의 | +|------|------| +| **계약 (Contract)** | 에이전트의 계획 수립 행위에 대한 명시적 약속 및 조건 | +| **조항 (Clause)** | 계약의 구성 단위로서 특정 요구사항을 표현 | +| **검증 기준 (Verification Criteria)** | 조항의 성립 여부를 판단하는 성공/실패 조건 | +| **계획 (Plan)** | 목표 달성을 위한 단계별 행동 시퀀스 | +| **에피타이드 (Epitaph)** | 계획 실행 결과의 기록 및 평가 | + +--- + +## 계약 조항 명세 + +### 조항 1: 목표 명확성 (Goal Clarity) + +**설명**: 수립된 계획은 명확하고 측정 가능한 목표를 포함해야 한다. + +**검증 기준**: + +| 구분 | 조건 | +|------|------| +| **성공 조건** | - 목표가 구체적인 수치 또는 상태로 표현됨
- 목표 달성을 판단할 수 있는 명확한 기준 존재
- 목표가 단일 책임 원칙을 따름 (하나의 주요 결과) | +| **실패 조건** | - 목표가 모호한 표현으로 기술됨 (예: "좋게 만들기")
- 성공/실패 판단 기준이 없음
- 하나의 계획에 두 개 이상의 독립적 목표 포함 | + +--- + +### 조항 2: 단계 완전성 (Step Completeness) + +**설명**: 계획은 목표 달성까지 필요한 모든 단계를 포함해야 한다. + +**검증 기준**: + +| 구분 | 조건 | +|------|------| +| **성공 조건** | - 각 단계가 선행 조건을 만족함
- 모든 의존성 단계가 순서대로 배치됨
- 최종 단계에서 목표 달성 보장 | +| **실패 조건** | - 필수 단계가 누락됨
- 단계 간 의존성 순서 위반
- 목표에 도달하지 않는 불완전한 시퀀스 | + +--- + +### 조항 3: 실행 가능성 (Executability) + +**설명**: 계획의 각 단계는 현재 환경에서 실행 가능한 명령이어야 한다. + +**검증 기준**: + +| 구분 | 조건 | +|------|------| +| **성공 조건** | - 각 단계의 명령어가 시스템에서 사용 가능함
- 필요한 리소스(파일, 권한, 도구)가 확보됨
- 단계 실행에 대한 타임아웃이 설정됨 | +| **실패 조건** | - 존재하지 않는 명령어 또는 도구 참조
- 필요한 리소스 접근 권한 없음
- 무한 대기 가능성이 있는 단계 포함 | + +--- + +### 조항 4: 리스크 평가 (Risk Assessment) + +**설명**: 계획은 잠재적 리스크를 식별하고 완화 전략을 포함해야 한다. + +**검증 기준**: + +| 구분 | 조건 | +|------|------| +| **성공 조건** | - 각 단계별 잠재적 리스크 명시됨
- 리스크 발생 시 대안 경로 또는 복구 전략 존재
- 중요 리스크에 대한 회피 또는 감소 조치 포함 | +| **실패 조건** | - 리스크 식별 없이 진행
- 복구 전략 없는 단일 실패 지점 존재
- 치명적 리스크에 대한 무시 | + +--- + +### 조항 5: 검증 가능성 (Verifiability) + +**설명**: 계획의 각 단계는 실행 후 결과를 검증할 수 있어야 한다. + +**검증 기준**: + +| 구분 | 조건 | +|------|------| +| **성공 조건** | - 각 단계에 대한 예상 결과 명시됨
- 성공/실패를 판단하는 어설션 존재
- 검증 방법이 자동화 가능함 | +| **실패 조건** | - 단계 실행 결과 확인 방법 없음
- 주관적 판단에만 의존하는 검증
- 검증 불가능한 상태 변경 포함 | + +--- + +### 조항 6: 시간적 제약 (Temporal Constraints) + +**설명**: 계획은 실행 시간에 대한 합리적인 제약 조건을 포함해야 한다. + +**검증 기준**: + +| 구분 | 조건 | +|------|------| +| **성공 조건** | - 전체 계획에 대한 예상 소요 시간 명시
- 각 단계별 타임아웃 설정
- 시간 초과 시 대체 전략 존재 | +| **실패 조건** | - 시간 제약 없이 무한 대기 가능
- 현실적이지 않은 시간 추정
- 타임아웃 없는 장시간 작업 | + +--- + +### 조항 7: 롤백 가능성 (Rollback Capability) + +**설명**: 계획은 실패 시 이전 상태로 복구할 수 있는 메커니즘을 포함해야 한다. + +**검증 기준**: + +| 구분 | 조건 | +|------|------| +| **성공 조건** | - 각 변경 단계에 대한 롤백 명령 정의됨
- 롤백 실행 순서가 명확함
- 롤백 성공 여부 검증 방법 존재 | +| **실패 조건** | - 롤백 메커니즘 없음
- 일관성 없는 롤백 시퀀스
- 롤백 불가능한 영구 변경 포함 | + +--- + +## 계약 등급 + +| 등급 | 충족 조항 수 | 설명 | +|------|-------------|------| +| **A (최상)** | 7/7 | 모든 조항 충족, 최고 품질 보장 | +| **B (양호)** | 5-6/7 | 주요 조항 충족, 일부 개선 필요 | +| **C (미흡)** | 3-4/7 | 기본 구조는 있으나 신뢰성 낮음 | +| **D (위험)** | 1-2/7 | 심각한 결함, 실행 권장 불가 | +| **F (실패)** | 0/7 | 계약 미충족, 계획 부적격 | + +--- + +## 검증 프로세스 + +``` +┌─────────────┐ ┌──────────────┐ ┌─────────────┐ +│ 계획 수립 │───▶│ 계약 검증 │───▶│ 등급 부여 │ +└─────────────┘ └──────────────┘ └─────────────┘ + │ + ▼ + ┌──────────────┐ + │ 실패 조항 분석 │ + └──────────────┘ +``` + +--- + +## 에피타이드 기록 스키마 + +```json +{ + "planId": "string", + "timestamp": "ISO8601", + "grade": "A|B|C|D|F", + "clauses": { + "goalClarity": { "passed": boolean, "details": "string" }, + "stepCompleteness": { "passed": boolean, "details": "string" }, + "executability": { "passed": boolean, "details": "string" }, + "riskAssessment": { "passed": boolean, "details": "string" }, + "verifiability": { "passed": boolean, "details": "string" }, + "temporalConstraints": { "passed": boolean, "details": "string" }, + "rollbackCapability": { "passed": boolean, "details": "string" } + }, + "executionResult": { + "status": "success|partial|failure", + "duration": "number (ms)", + "deviationFromPlan": "string|null" + } +} +``` + +--- + +## 변경 이력 + +| 버전 | 날짜 | 변경 내용 | +|------|------|----------| +| 1.0.0 | 2026-07-14 | 초기 버전 작성 |