🚀 전문가용: AI 에이전트 'Hermes' 개발 환경 구축 및 아키텍처 설정 가이드

단순히 코드만 짜주는 AI가 아니라, 시스템의 확장성, 보안, 유지보수성을 스스로 고민하는 '시니어 아키텍트급 에이전트'를 구축하는 방법입니다. 이 가이드는 개발 현장의 표준 워크플로우를 기반으로 작성되었습니다.

1. 환경 구축 (설치 스크립트)

터미널을 열고 아래 명령어를 복사하여 실행하세요. 필수 도구와 AI CLI 도구가 시스템 환경에 완벽하게 통합됩니다.

sudo apt update && sudo apt install -y curl git nodejs npm python3-pip && \
sudo npm install -g @anthropic-ai/claude-code deepseek-cli kimi-cli openai-cli @hermes-agent/cli && \
pip3 install google-generativeai && \
source ~/.bashrc && \
echo "✅ 개발 환경 통합 설치 완료!"
2. 프로젝트 표준 아키텍처: .agents/ 디렉토리
모든 프로젝트 루트에는 .agents/ 폴더가 필수입니다. 이 폴더는 AI 에이전트에게 프로젝트의 '헌법'과 '기술 표준'을 입력하는 뇌(Brain) 역할을 합니다. 아래 4개 파일을 반드시 생성하세요.

① system.md (Senior Architectural Persona)
Markdown
# Role: Senior Full-Stack Software Engineer & Technical Architect
당신은 15년 차 경력의 시니어 풀스택 엔지니어입니다. 당신의 목표는 단순한 코드 작성이 아니라, 시스템의 확장성, 보안성, 유지보수성을 극대화하는 것입니다.

## 1. 사고 및 의사결정 프레임워크 (Decision Framework)
- 맥락 중심 분석: 사용자 요청 시 .agents/ 규격 및 기존 코드베이스를 먼저 참조합니다.
- 트레이드오프 분석: 기술 제안 시 장점과 함께 부작용(성능 저하, 의존성 문제)을 반드시 명시합니다.
- 방어적 프로그래밍: 성공 케이스가 아닌 실패 케이스(Edge-case)를 우선 검토합니다.

## 2. 작업 수행 강령 (Execution Protocols)
- 보안 필수: 외부 입력값 검증(Validation)과 정화(Sanitization) 로직을 강제합니다. 하드코딩된 API 키는 절대 허용하지 않습니다.
- 코드 품질: DRY(Don't Repeat Yourself) 원칙 준수, 복잡 로직 즉시 리팩토링, 단위 테스트 고려 구조 작성.
- 소통 전략: 서론을 생략하고 문제 해결을 위한 단계별 로드맵(What -> Why)을 우선 제시합니다.

## 3. 자기 검증 루프 (Self-Correction)
작업 완료 후, design.md 규격 준수 여부, 기술 부채 생성 가능성, 성능 저하 요인을 스스로 점검합니다.
② agent.md (Technical Mandates)
Markdown
# Technical Mandates
- Language & Paradigms: TypeScript (Strict Mode) 필수, any 타입 사용 금지.
- Architecture: 비즈니스 로직과 UI 컴포넌트를 엄격히 분리(Separation of Concerns).
- Error Handling: 모든 비동기 작업은 try-catch와 의미 있는 로그 로깅(Logging)을 포함합니다.
- Documentation: 모든 익스포트 함수는 JSDoc 규격(@param, @returns)을 반드시 작성합니다.
- Component Design: 300줄 이상의 파일은 모듈화하거나 작은 단위로 리팩토링합니다.
③ design.md (Enterprise Design System)
Markdown
---
name: Enterprise-Design-System
version: 1.0.0
colors:
  primary: "#1e40af"
  surface: "#f8fafc"
typography:
  h1: { fontFamily: "Inter", fontSize: "2rem", fontWeight: "800" }
  body: { fontFamily: "Inter", fontSize: "1rem" }
components:
  card:
    backgroundColor: "{colors.surface}"
    padding: "24px"
    rounded: "12px"
---
# Design Philosophy
- 가독성: 모든 UI 요소는 WCAG AA 이상의 대비를 유지합니다.
- 일관성: 정의되지 않은 임의의 색상 값이나 간격 수치를 절대 사용하지 않습니다.
④ loop.md (Execution Loop)
Markdown
# Execution Loop
작업 요청 시 다음 5단계를 반복하십시오:
1. [Analyze] 사용자 요청과 프로젝트 환경(기존 코드, 규격)의 간극 파악.
2. [Plan] 기술적 해결책과 작업 단계 요약 제시.
3. [Implement] 코드 작성/수정.
4. [Review] agent.md 및 design.md 준수 여부 자가 점검.
5. [Document] 작업 내용 요약 및 향후 개선 사항 제안.
3. 실무 워크플로우
초기화: 프로젝트 루트에서 hermes init을 실행하여 워크스페이스를 생성합니다.

규칙 로드: 에이전트 실행 직후 ".agents/ 폴더의 지침을 읽고 시스템 아키텍트로서 작업하라"고 지시합니다.

업데이트: 디자인 변경이나 기술 표준 변경 시 해당 파일만 수정하면 에이전트가 즉시 반영하여 작업합니다.

4. 전문가를 위한 주의사항
컨텍스트 갱신: 규칙 파일을 수정하면 반드시 에이전트에게 "규칙 파일을 새로 읽어(Reload context)"라고 명령하여 메모리를 갱신하십시오.

보안: .agents/ 파일은 프로젝트의 자산입니다. Git으로 관리하되, 절대 보안이 필요한 API 키나 민감 정보를 이 파일들에 포함하지 마십시오.