dd34a7f97a
Agents: workspace-mover, path-updater, integrity-checker
Skill: workspace-reorganize-orchestrator (pipeline)
CLAUDE.md: harness pointer registered
Target: itsm/->workspace/guardia-itsm, manager/->workspace/guardia-manager,
app/->workspace/guardia-messenger, manual/->workspace/guardia-docs
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
11 KiB
GUARDiA — AI 기반 레거시 인프라 자율 운영 플랫폼
Claude Code용 프로젝트 마스터 컨텍스트 파일 이 파일을 읽고 프로젝트의 전체 구조와 규칙을 파악한 뒤 작업을 시작하라.
프로젝트 비전
1,000개 이상의 다중 관공서(Multi-tenant) 레거시 인프라를 타겟으로 하는
AI 기반 통합 ChatOps 오케스트레이션 플랫폼.
- 메신저 한 줄 명령 → sLLM 파싱 → 에이전트리스(SSH/SFTP) 배포·운영 자동화
- 에이전트 설치 불필요 — 표준 SSH/FTP 프로토콜만 활용
- 개발(Dev), SM 운영, PM 관리 세 역할의 워크플로우를 단일 메신저로 통합
디렉터리 구조
C:\GUARDiA\
├── CLAUDE.md # ← 지금 이 파일 (Claude Code 진입점)
├── docs/
│ ├── system_spec.md # 전체 시스템 아키텍처 명세
│ ├── ARCHITECTURE.md # 3계층 아키텍처 + 구현 로드맵
│ ├── ai_orchestration.md # AI 에이전트 워크플로우 규격
│ ├── db_schema.md # CMDB + SR + Audit + 신규 테이블 DDL
│ ├── messenger_integration.md # 메신저 웹훅 & sLLM 연동 명세
│ ├── deployment_engine.md # 에이전트리스 배포 엔진 명세
│ ├── security_governance.md # 보안·권한·감사 정책
│ ├── shell_scripts_guide.md # SM용 원격 제어 쉘 스크립트 + 관리 DB
│ ├── site_user_management.md # 사이트/사용자 등록관리 명세 (신규)
│ └── work_timetable.md # 작업 타임테이블 + Excel 다운로드 명세 (신규)
├── itsm/ # GUARDiA ITSM 웹 애플리케이션
│ ├── main.py # FastAPI 앱 진입점 (포트 8001)
│ ├── models.py # SQLAlchemy ORM 모델 + Pydantic 스키마
│ ├── database.py # DB 연결 및 세션
│ ├── core/
│ │ ├── auth.py # JWT 인증, RBAC
│ │ └── events.py # SSE 실시간 이벤트 버스
│ ├── routers/
│ │ ├── tasks.py # SR CRUD + 상태 전이
│ │ ├── approvals.py # PM 승인 워크플로우
│ │ ├── dashboard.py # 대시보드 통계 + SSE + 7일 추이
│ │ ├── cmdb.py # CMDB 서버 자산 조회
│ │ ├── kb.py # 기술 문서 지식베이스
│ │ ├── assign.py # 엔지니어 자동 배정
│ │ ├── ai_cmd.py # AI 자연어 명령 인터페이스
│ │ ├── institutions.py # 기관/사이트 + 담당자 관리 (신규)
│ │ ├── servers.py # 서버 자산 확장 관리 (신규)
│ │ ├── shell_scripts.py # 쉘 스크립트 라이브러리 CRUD (신규)
│ │ └── timetable.py # 작업 타임테이블 + Excel 다운로드 (신규)
│ └── static/
│ ├── index.html # SPA 진입점
│ ├── app.js # 프론트엔드 로직 (64 KB)
│ └── style.css # Nifty 다크 테마 CSS
├── skills/
│ ├── guardia-deploy/SKILL.md # 배포 엔진 구현 스킬
│ ├── guardia-agent/SKILL.md # Python 역방향 에이전트 스킬
│ └── guardia-messenger/SKILL.md # 메신저 연동 스킬
└── src/ (생성 예정)
├── api/ # FastAPI 백엔드
├── agent/ # Python 역방향 에이전트
├── llm/ # sLLM 파서 모듈
├── deploy/ # SSH/SFTP 배포 엔진
└── db/ # DB 마이그레이션 & 모델
기술 스택 (변경 금지)
| 레이어 | 기술 | 비고 |
|---|---|---|
| Backend API | Python 3.11+ / FastAPI | 비동기 WebSocket 처리 |
| LLM | 온프레미스 sLLM (Llama-3-8B / Solar-10.7B) | 외부 API 호출 절대 금지 |
| Infra 연결 | paramiko (SSH/SFTP) |
에이전트리스 |
| Database | PostgreSQL (CMDB + SR + Audit) | |
| 배포 자동화 | 쉘 스크립트 + Ansible (선택) | |
| 프론트 | React.js 또는 HTML5/Vanilla JS |
핵심 구현 원칙
- 에이전트리스: 대상 서버에 어떤 소프트웨어도 설치하지 않는다.
- 결정론적 파싱: sLLM은 JSON만 출력한다. 자연어 부연 설명 금지.
- Fail-Safe: 모든 배포는 백업 → 배포 → 헬스체크 → 롤백 시퀀스를 따른다.
- 감사 추적: 모든 명령과 결과는
TB_AUDIT_LOG에 기록한다. - 최소 권한: 관제 전용 일반 계정(opsagent) 사용. root SSH 직접 접속 금지.
- 보안 우선: 서버 자격증명은 암호화 DB에만 저장. 메신저 응답에 노출 금지.
작업 시작 순서 (권장)
1단계: docs/db_schema.md 읽기 → PostgreSQL DDL 작성
2단계: docs/messenger_integration.md 읽기 → FastAPI 웹훅 서버 구현
3단계: docs/deployment_engine.md 읽기 → SSH/SFTP 배포 엔진 구현
4단계: docs/ai_orchestration.md 읽기 → sLLM 파서 & 워크플로우 연동
5단계: docs/security_governance.md 읽기 → 권한 검증 & 감사 모듈 구현
6단계: docs/site_user_management.md 읽기 → 기관/담당자/서버 자산 확장 구현
7단계: docs/shell_scripts_guide.md 읽기 → 쉘 스크립트 DB 관리 구현
8단계: docs/work_timetable.md 읽기 → 타임테이블 + Excel 다운로드 구현
Workspace 소스 분석 워크플로우
사용법:
C:\GUARDiA\workspace\<프로젝트명>\폴더에 소스코드를 넣는다- Claude에게 "workspace에 소스 넣었어" 또는 "분석해줘" 라고 말한다
workspace-analyzer스킬이 자동으로:- 기술스택 탐지 (Java/Python/Node.js/PHP 등)
- 개발환경 설치 가이드 제공
.claude/하네스 자동 생성 (에이전트 + 스킬)CLAUDE.md자동 생성
트리거: workspace-analyzer 스킬을 사용하라 — "소스 분석", "workspace", "개발환경 가이드", "하네스 적용" 요청 시.
하네스: GUARDiA ITSM
목표: SR 접수·배포·코드리뷰·SLA·인시던트·RCA·보안패치 등 ITSM 운영 전반 자동화
트리거: ITSM 운영 관련 작업 요청 시 guardia-orchestrator 스킬을 사용하라.
단순 질문(API 경로, 모델 설명 등)은 직접 응답 가능.
변경 이력:
| 날짜 | 변경 내용 | 대상 | 사유 |
|---|---|---|---|
| 2026-05-20 | 초기 하네스 구성 | 전체 | GUARDiA ITSM 30개 고도화 항목 완료 |
| 2026-05-29 | G-1~G-12 확장 기능 구현 | 오케스트레이터, sr-manager, incident-responder, deploy-engineer | 메신저봇/대량처리/자동RCA/영향분석/AI분류/패치추적/Jira/PWA/다중승인/PostgreSQL |
| 2026-05-29 | 봇 명령어 확장 (/sr /status /license /bulk) | messenger.py | 슬래시 스타일 명령어 추가 |
| 2026-05-29 | 설치 스크립트 추가 | setup/ | Ubuntu/CentOS/RHEL/Windows 설치 자동화 |
| 2026-05-31 | DR·네트워크·CSAP 3종 추가 | dr-coordinator, network-guardian, csap-auditor + 스킬 3종 + 라우터 3종 | DR자동화/네트워크장비관리/CSAP자동점검 |
하네스: GUARDiA Manager
목표: GUARDiA ITSM·홈페이지·서버 인프라·CI/CD 통합 관제 관리자 포털 구축
참조 디자인: 네이버 클라우드 콘솔(NCloud Console) 패턴 적용.
메인화면: 대시보드 차트 중심 (SR 추이·서버 상태·리소스·배포 이력).
트리거: C:\GUARDiA\manager 관련 작업 요청 시 manager-orchestrator 스킬을 사용하라.
M-01 대시보드, 관리자 UI, Manager 배포, 다시 실행, 업데이트 요청 시 포함.
변경 이력:
| 날짜 | 변경 내용 | 대상 | 사유 |
|---|---|---|---|
| 2026-05-30 | 초기 하네스 구성 | 전체 | GUARDiA Manager 신규 구축 |
| 2026-05-30 | 라이선스·Export-Import·AI플랫폼·GUARDiA CI-CD·SMTP 구축 | 다수 | 추가 기능 완료 |
하네스: workspace 통합 재구성
목표: itsm/, manager/, app/, manual/을 workspace/ 하위로 통합. git mv로 히스토리 보존, 모든 경로 참조 업데이트.
트리거: workspace로 이동, 소스 workspace 통합, 프로젝트별 workspace 정리 요청 시 workspace-reorganize-orchestrator 스킬을 사용하라.
목표 구조:
workspace/
├── zioinfo-web/ (현재 위치 유지)
├── guardia-itsm/ ← itsm/
├── guardia-manager/ ← manager/
├── guardia-messenger/ ← app/
└── guardia-docs/ ← manual/
변경 이력:
| 날짜 | 변경 내용 | 대상 | 사유 |
|---|---|---|---|
| 2026-05-31 | 초기 하네스 구성 | 전체 | workspace 통합 요청 |
하네스: 레파지토리 분리
목표: C:\GUARDiA 모노레포를 4개 독립 Gitea 저장소로 분리. GitHub 제거, Gitea 전용 운영.
트리거: 레파지토리 분리, 저장소 분리, repo 분리, GitHub 제거, Gitea 전용 운영 요청 시 repo-split-orchestrator 스킬을 사용하라.
변경 이력:
| 날짜 | 변경 내용 | 대상 | 사유 |
|---|---|---|---|
| 2026-05-31 | 초기 하네스 구성 | 전체 | 모노레포 → 독립 repo 전환 요청 |
하네스: UI 전면 개편
목표: Playwright MCP + Variant(variant.com/community)로 zio 4개 시스템(홈페이지·ITSM·Manager·Messenger) UI를 전면 개편. Before/After 시각적 비교 + 통합 디자인 토큰 적용.
트리거: UI 개편, 디자인 전면 개편, Variant 활용, 디자인 토큰, Before/After 비교, 컴포넌트 리팩토링 요청 시 ui-overhaul-orchestrator 스킬을 사용하라.
메신저 봇 명령어 (/design):
/design capture → Playwright MCP로 현재 UI 스크린샷 캡처
/design variant <검색어> → Variant에서 디자인 레퍼런스 탐색
/design tokens → 통합 tokens.css 생성
/design <시스템> → 특정 시스템 컴포넌트 개편 (homepage/itsm/manager/app)
/design qa → Before/After 시각적 QA
/design ab <컴포넌트> → A/B 테스트 컴포넌트 생성
변경 이력:
| 날짜 | 변경 내용 | 대상 | 사유 |
|---|---|---|---|
| 2026-05-31 | 초기 하네스 구성 | 전체 | 99.디자인전면개편.md 기반 |
보안 제약 (불변)
아래 규칙은 어떤 상황에서도 위반 불가
| 규칙 | 내용 |
|---|---|
| 외부 API 금지 | on-premise sLLM(Ollama)만 허용. 외부 호출 절대 금지 |
| 자격증명 보호 | IP, SSH계정, 비밀번호를 API 응답/메신저/에러메시지에 절대 노출 금지 |
| 암호화 필수 | os_pw_enc 컬럼 AES-256-GCM 암호화 저장 필수 |
| root 금지 | root SSH 직접 접속 금지 — opsagent 전용 계정 사용 |
| 에러 응답 | 스택트레이스 미노출 — SR ID + 요약 메시지만 전달 |
| ServerOut 스키마 | ip_addr, ssh_user, os_pw_enc 컬럼 API 응답에서 완전 제외 |
스킬 파일 참조 방법
특정 기능 구현 전 해당 스킬 파일을 반드시 먼저 읽어라.
- 배포 엔진 작업 시 →
skills/guardia-deploy/SKILL.md - 역방향 에이전트 작업 시 →
skills/guardia-agent/SKILL.md - 메신저 연동 작업 시 →
skills/guardia-messenger/SKILL.md