45f96176a6
- CLAUDE.md: project context and architecture spec - docs/: system specs, DB schema, messenger integration, deployment engine - skills/: guardia-deploy, guardia-agent, guardia-messenger - .claude/settings.json: project-level permissions - .gitignore: Python/FastAPI project Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
163 lines
4.8 KiB
Markdown
163 lines
4.8 KiB
Markdown
# [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`)
|
|
|
|
```markdown
|
|
## 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`)
|
|
|
|
```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 스키마
|
|
|
|
```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 흐름
|
|
|
|
```python
|
|
# 작업 완료 → 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. 작업 관리 엔진 핵심 코드 구조
|
|
|
|
```python
|
|
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)`
|
|
- 위변조 탐지: 매시간 해시 체인 연결성 자동 검증
|