zioinfo-mail/docs/ai_orchestration.md

[Specification] AI Agent Workflow & SR Task Execution

본 문서는 SR 접수부터 AI 에이전트(Claude Code)의 실제 작업 수행까지의 연동 규격이다.

---

1. SR Task Handling Logic

Reception  → 메신저 SR을 파싱 서버가 TB_SR_REQUEST에 정형 데이터로 저장
         ↓
Prioritization → PM 우선순위 부여 → 작업 관리 엔진이 큐에 적재
         ↓
Execution Context → 작업 관리 엔진이 context.md를 프로젝트 루트에 생성
         ↓
Claude Code → context.md 읽고 작업 범위 파악 → 수행
         ↓
Result → result.json 저장 → DB 업데이트 → 메신저 완료 통보

상태 전이 (State Machine)

RECEIVED → PARSED → PENDING_APPROVAL → APPROVED → IN_PROGRESS → COMPLETED
                                                           ↓
                                                    FAILED_ROLLBACK

---

2. Claude Code Interaction Pattern

2.1. Context 파일 생성 규격 (context.md)

## Task Context
- SR_NO: {sr_number}
- Institution: {institution_name}
- System: {system_name}
- Target Nodes: {node_list}
- Action: {action_type}  # DEPLOY / LOG_ANALYSIS / RESTART / SSL_CHECK
- Artifacts: {file_paths}
- Constraints: {policy_rules}

2.2. Result 파일 규격 (result.json)

{
  "sr_no": "SR-2026-001",
  "status": "SUCCESS",          // SUCCESS | FAILED | PARTIAL
  "changed_files": [],
  "execution_log": "...",
  "health_check": {"status": "200 OK"},
  "rollback_available": true,
  "completed_at": "2026-05-23T19:00:00Z"
}

---

3. sLLM Deterministic Parser

3.1. System Prompt (엄격 적용)

[SYSTEM PROMPT — 절대 변경 금지]
당신은 인프라 자동화 시스템의 핵심 파서입니다.
1. 사용자의 자연어를 분석하여 JSON 출력물만 생성합니다.
2. 부연 설명, 인삿말, 안내 텍스트는 절대 포함하지 않습니다.
3. CMDB에 정의된 정확한 서버 ID와 매핑되지 않는 정보는 "UNKNOWN"으로 처리합니다.
4. 배포 명령 시 반드시 'requires_approval'(boolean) 값을 판단합니다.

3.2. 출력 JSON 스키마

{
  "intent_type": "DEPLOY_UPGRADE | LOG_ANALYSIS | SERVICE_RESTART | SSL_CHECK | DB_QUERY | CRON_MANAGE",
  "institution": "기관명",
  "system_name": "시스템명",
  "infrastructure_layer": "WEB | WAS | DB | ESB",
  "target_nodes": ["NODE_01", "NODE_02"],
  "action_sequence": ["UPLOAD", "BACKUP", "REPLACE", "ROLLING_RESTART"],
  "deploy_artifacts": ["class", "html", "js", "image"],
  "requires_approval": false,
  "priority": "HIGH | MEDIUM | LOW"
}

---

4. Deployment Integration

4.1. 정적 vs 동적 자원 처리

자원 타입	WAS 재기동 필요	처리 방식
html, js, css, image	❌	SFTP 카피 → 즉시 반영
.class, .jar, .war	✅	백업 → 롤링 재기동
config 파일	✅ (서비스에 따라)	확인 후 결정

4.2. 무중단 롤링 배포 시퀀스

WAS #1:
  1. L4/Nginx에서 트래픽 차단
  2. 현재 버전 백업 (mv app.jar app.jar.bak_YYYYMMDD)
  3. SFTP로 신규 파일 전송 + md5sum 무결성 검증
  4. shutdown.sh 실행 → startup.sh 실행
  5. curl -I http://localhost:8080 → 200 OK 확인 (timeout 30s)
  6. 실패 시 즉시 rollback.sh 실행

WAS #2: WAS #1 완료 확인 후 동일 시퀀스 반복

4.3. PM 승인 HITL 흐름

# 작업 완료 → PM에게 Result Package 전송
def notify_pm_for_approval(sr_id, package):
    summary = f"[{sr_id}] 작업 완료\n헬스체크: {package['health']['status']}"
    messenger.send_approval_request(
        target="PM_TEAM",
        message=summary,
        callback_url=f"/api/sr/approve/{sr_id}"
    )

# PM 승인 시 고객 완료 통보
@app.post("/api/sr/approve/{sr_id}")
def finalize_sr(sr_id: str):
    db.update_sr_status(sr_id, "COMPLETED")
    messenger.send_message(requester, f"SR-{sr_id} 배포 완료")

---

5. 작업 관리 엔진 핵심 코드 구조

class TaskManager:
    def process_task_completion(self, sr_id, work_dir):
        result_package = self._collect_result_package(work_dir)
        self._notify_pm_for_approval(sr_id, result_package)
        self.db.update_sr_status(sr_id, "PENDING_PM_VALIDATION")

    def _collect_result_package(self, work_dir):
        return {
            "diff": open(f"{work_dir}/changes.diff").read(),
            "logs": open(f"{work_dir}/execution.log").read(),
            "health": json.load(open(f"{work_dir}/health_check.json"))
        }

---

6. 로깅 및 감사 표준

• 모든 작업 이력: JSON Lines 포맷 → audit_logs/ 디렉토리
• 감사 로그 SHA-256 해시 체이닝:
  Log[n].hash = SHA256(Log[n].data + Log[n-1].hash)
• 위변조 탐지: 매시간 해시 체인 연결성 자동 검증