Agentic OS
Claude Code를 채팅 세션이 아닌 지속적인 런타임/운영 체제로 취급합니다. 이 스킬은 프로덕션 에이전트 설정에서 사용되는 아키텍처를 체계화합니다: 작업을 전문 에이전트에게 라우팅하는 커널 설정, 지속적인 파일 기반 메모리, 예약된 자동화, JSON/마크다운 데이터 계층으로 구성됩니다.
활성화 시점
- Claude Code 내에서 멀티 에이전트 워크플로우 구축
- 세션 재시작에도 유지되는 지속적인 Claude Code 자동화 설정
- 반복 작업을 위한 '개인 OS' 또는 '에이전트 OS' 생성
- 사용자가 'agentic OS', 'personal OS', 'multi-agent', 'agent coordinator', 'persistent agent'라고 말할 때
- 컨텍스트가 세션 간에 유지되어야 하는 장기 실행 프로젝트 구성
아키텍처 개요
Agentic OS는 네 개의 레이어로 구성됩니다. 각 레이어는 프로젝트 루트의 디렉터리입니다.
project-root/
├── CLAUDE.md # 커널: 정체성, 라우팅 규칙, 에이전트 레지스트리
├── agents/ # 전문 에이전트 정의 (마크다운 프롬프트)
├── .claude/commands/ # 슬래시 명령어: 사용자 대상 CLI
├── scripts/ # 데몬 스크립트: 예약 또는 이벤트 기반 작업
└── data/ # 상태: JSON/마크다운 파일 시스템, 외부 DB 없음
레이어 책임
| 레이어 | 목적 | 지속성 |
|---|---|---|
커널 (CLAUDE.md) | 정체성, 라우팅, 모델 정책, 에이전트 레지스트리 | Git 추적 |
에이전트 (agents/) | 범위가 지정된 도구와 메모리를 가진 전문 정체성 | Git 추적 |
명령어 (.claude/commands/) | 사용자 대상 슬래시 명령어 (/daily-sync, /outreach) | Git 추적 |
스크립트 (scripts/) | cron 또는 웹훅으로 트리거되는 Python/JS 데몬 | Git 추적 |
상태 (data/) | 추가 전용 로그, 프로젝트 상태, 의사결정 기록 | Git 무시 또는 추적 |
커널
CLAUDE.md는 커널입니다. COO/오케스트레이터 역할을 합니다. Claude는 세션 시작 시 이를 읽고 작업을 라우팅하는 데 사용합니다.
커널 구조
# CLAUDE.md - Agentic OS 커널
## 정체성
당신은 [프로젝트 이름]의 COO입니다. 작업을 전문 에이전트에게 라우팅합니다.
코드를 직접 작성하지 않습니다. 올바른 에이전트에게 위임하고 결과를 종합합니다.
## 에이전트 레지스트리
| 에이전트 | 역할 | 트리거 |
|---|---|---|
| @dev | 코드, 아키텍처, 디버깅 | 사용자가 "빌드", "수정", "리팩터"라고 말함 |
| @writer | 문서, 콘텐츠, 이메일 | 사용자가 "작성", "초안", "블로그"라고 말함 |
| @researcher | 연구, 분석, 사실 확인 | 사용자가 "연구", "분석", "비교"라고 말함 |
| @ops | DevOps, 배포, 인프라 | 사용자가 "배포", "CI", "서버"라고 말함 |
## 라우팅 규칙
1. 사용자 요청에서 의도 키워드 구문 분석
2. 에이전트 레지스트리 트리거 열과 일치
3. `agents/<name>.md`에서 해당 에이전트 파일 로드
4. 전체 컨텍스트와 함께 실행 위임
5. 결과를 종합하여 사용자에게 제시
## 모델 정책
- 기본 모델: 저장소 또는 하네스 기본값 사용.
- @dev 작업: 복잡한 아키텍처에는 더 높은 추론 모델 선호.
- @researcher 작업: 구성된 연구 가능 모델과 승인된 검색 도구 사용.
- 비용 상한: 프로젝트의 구성된 지출 임계값을 초과하기 전에 경고.
핵심 원칙
커널은 작고 선언적이어야 합니다. 라우팅 로직은 코드가 아닌 일반 마크다운 테이블에 존재합니다. 이렇게 하면 디버깅 없이 시스템을 검사하고 편집할 수 있습니다.
전문 에이전트
각 에이전트는 agents/ 디렉터리의 독립적인 마크다운 파일입니다. Claude는 작업을 라우팅할 때 해당 에이전트 파일을 로드합니다.
에이전트 정의 형식
# @dev - 소프트웨어 엔지니어
## 정체성
당신은 시니어 소프트웨어 엔지니어입니다. 깨끗하고 테스트된 프로덕션 수준의 코드를 작성합니다.
간단한 솔루션을 선호합니다. 요구 사항이 모호할 때 명확한 질문을 합니다.
## 메모리 범위
- 컨텍스트를 위해 `data/projects/<현재-프로젝트>.md` 읽기
- 아키텍처 결정을 위해 `data/decisions/` 읽기
- 실행 로그를 `data/logs/<날짜>[email protected]`에 추가
## 도구 접근
- 프로젝트 루트 내 전체 파일 시스템 접근
- Git 작업 (status, diff, commit, branch)
- 테스트 러너 접근
- `.claude/mcp.json`에 구성된 MCP 서버
## 제약 조건
- 새 기능에는 항상 테스트 작성
- `main`에 직접 커밋하지 않음; 기능 브랜치 사용
- 새 파일 생성보다 기존 파일 편집 선호
- 가능한 경우 함수를 50줄 미만으로 유지
다중 에이전트 협업 패턴
작업이 여러 에이전트에 걸쳐 있을 때 커널이 순차적 또는 병렬로 실행합니다:
사용자: "랜딩 페이지를 구축하고 출시 블로그 게시물을 작성해줘"
커널 라우팅:
1. @dev - "[요구 사항]에 따라 랜딩 페이지 구축"
2. @writer - "랜딩 페이지 카피를 사용하여 [제품] 출시 블로그 게시물 작성"
3. 커널이 두 출력을 통합 응답으로 종합
병렬 실행의 경우, Claude Code의 백그라운드 작업 기능이나 특정 에이전트 컨텍스트로 Claude Code를 호출하는 셸 스크립트를 사용하세요.
명령어와 일일 워크플로우
슬래시 명령어는 .claude/commands/ 디렉터리의 마크다운 파일입니다. 재사용 가능한 워크플로우를 정의합니다.
명령어 구조
# /daily-sync
아침 브리핑 실행:
1. 컨텍스트를 위해 `data/logs/last-sync.md` 읽기
2. 프로젝트 상태 확인: `git status`, 대기 중인 PR, CI 상태
3. 새 작업이나 필요한 결정을 위해 `data/inbox/` 검토
4. 차단 항목, 우선순위, 다음 조치 요약 생성
5. 브리핑을 `data/logs/daily/<날짜>.md`에 추가
표준 명령어 세트
| 명령어 | 목적 |
|---|---|
/daily-sync | 아침 브리핑: 상태, 차단 항목, 우선순위 |
/outreach | 아웃리치 워크플로우 실행 (이메일, LinkedIn 등) |
/research <주제> | 인용 추적을 통한 심층 연구 |
/apply-jobs | 대상 역할에 맞게 이력서 + 자기소개서 조정 |
/analytics | Stripe, GitHub 또는 사용자 정의 소스에서 지표 가져오기 |
/interview-prep | 플래시카드 또는 모의 면접 질문 생성 |
/decision <주제> | 장단점과 선택한 경로로 결정 기록 |
명령어 활성화
명령어 파일을 .claude/commands/<명령어-이름>.md에 배치하세요. Claude Code가 자동으로 발견합니다. 사용자는 /<명령어-이름>으로 호출합니다.
지속적인 메모리
메모리는 파일 기반입니다. 벡터 DB, Redis, PostgreSQL이 없습니다. data/의 JSON 및 마크다운 파일이 데이터베이스입니다.
메모리 디렉터리 구조
data/
├── daily-logs/ # 추가 전용 일일 활동 로그
├── projects/ # 프로젝트별 컨텍스트 파일
├── decisions/ # 아키텍처 및 비즈니스 결정 (ADR 형식)
├── inbox/ # 분류 대기 중인 새 작업 또는 아이디어
├── contacts/ # 사람, 회사, 관계 메모
└── templates/ # 재사용 가능한 프롬프트 및 형식
일일 로그 형식
# 2026-04-22 - 일일 로그
## 세션
- 09:00 - 세션 1: 인증 모듈 리팩터링 (@dev)
- 11:30 - 세션 2: 투자자 업데이트 초안 작성 (@writer)
## 결정
- JWT에서 세션 쿠키로 전환 (`data/decisions/2026-04-22-auth.md` 참조)
## 차단 항목
- 공급업체의 API 키 대기 중 (2026-04-24 후속 조치)
## 다음 조치
- [ ] 인증 리팩터 PR 병합
- [ ] 투자자 업데이트 검토용 전송
자동 반영 패턴
각 세션이 끝날 때 커널이 반영을 추가합니다:
## 반영 - 세션 3
- 잘된 점: 병렬 에이전트 실행으로 20분 절약
- 아쉬운 점: @researcher가 페이월드 소스에 도달, 더 나은 소스 순위 필요
- 변경할 점: 연구 메모에 `source-tier` 필드 추가 (A/B/C 신뢰도)
이것은 코드 변경 없이 시간이 지남에 따라 시스템을 개선하는 피드백 루프를 만듭니다.
예약된 자동화
Agentic OS 작업은 Claude Code의 내장 cron(세션이 종료되면 사라짐)이 아닌 외부 cron을 사용하여 예약에 따라 실행됩니다.
macOS: LaunchAgent
<!-- ~/Library/LaunchAgents/com.agentic.daily-sync.plist -->
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" ...>
<plist version="1.0">
<dict>
<key>Label</key>
<string>com.agentic.daily-sync</string>
<key>ProgramArguments</key>
<array>
<string>/claude</string>
<string>--cwd</string>
<string>/path/to/project</string>
<string>--command</string>
<string>/daily-sync</string>
</array>
<key>StartCalendarInterval</key>
<dict>
<key>Hour</key>
<integer>8</integer>
<key>Minute</key>
<integer>0</integer>
</dict>
<key>StandardOutPath</key>
<string>/tmp/agentic-daily-sync.log</string>
</dict>
</plist>
Linux: systemd 타이머
# ~/.config/systemd/user/agentic-daily-sync.service
[Unit]
Description=Agentic OS Daily Sync
[Service]
Type=oneshot
ExecStart=/usr/local/bin/claude --cwd /path/to/project --command /daily-sync
# ~/.config/systemd/user/agentic-daily-sync.timer
[Unit]
Description=Run daily sync every morning
[Timer]
OnCalendar=*-*-* 8:00:00
Persistent=true
[Install]
WantedBy=timers.target
크로스 플랫폼: pm2
# ecosystem.config.js
module.exports = {
apps: [{
name: 'agentic-daily-sync',
script: 'claude',
args: '--cwd /path/to/project --command /daily-sync',
cron_restart: '0 8 * * *',
autorestart: false
}]
};
데이터 계층
데이터 계층은 파일 시스템입니다. 구조화된 데이터에는 JSON을 사용하고 서술적 콘텐츠에는 마크다운을 사용하세요.
구조화된 상태를 위한 JSON
// data/projects/website-v2.json
{
"name": "Website v2",
"status": "in-progress",
"milestone": "beta-launch",
"agents_involved": ["@dev", "@writer"],
"files": {
"spec": "docs/website-v2-spec.md",
"design": "designs/website-v2.fig"
},
"metrics": {
"commits": 47,
"last_session": "2026-04-22T11:30:00Z"
}
}
서술적 콘텐츠를 위한 마크다운
결정, 로그, 연구 노트, 연락처 기록 등 사람이 읽는 모든 것에는 마크다운을 사용하세요.
스키마 진화
기존 필드의 이름을 바꾸지 마세요. 새 필드를 추가하고 이전 필드는 폐기 대상으로 표시하세요:
{
"name": "Website v2",
"status": "in-progress",
"milestone": "beta-launch",
"_deprecated_priority": "high",
"priority_v2": { "level": "high", "rationale": "Blocks investor demo" }
}
이렇게 하면 마이그레이션 스크립트 없이도 과거 데이터를 읽을 수 있습니다.
안티 패턴
단일체 단일 에이전트
# 나쁨 - 하나의 에이전트가 모든 것을 함
당신은 풀스택 개발자이자 작가, 연구원, DevOps 엔지니어입니다.
전문 에이전트로 분할하세요. 커널이 라우팅을 처리합니다.
상태 비저장 세션
# 나쁨 - 세션 간 메모리 없음
Claude Code가 열릴 때마다 매번 새로 시작.
항상 세션 시작 시 data/를 읽고 세션 종료 시 다시 씁니다.
하드코딩된 자격 증명
# 나쁨 - 에이전트 파일이나 CLAUDE.md에 API 키
당신의 OpenAI API 키는 sk-xxxxxxxx입니다.
환경 변수 또는 스크립트에서 로드하는 .env 파일을 사용하세요. 에이전트는 process.env.API_KEY를 참조합니다.
간단한 상태를 위한 외부 데이터베이스
# 나쁨 - 단일 사용자의 에이전트 OS를 위해 PostgreSQL 사용
여러 동시 사용자 또는 GB 단위의 데이터가 있을 때까지 JSON/마크다운 파일을 사용하세요.
과도하게 설계된 라우팅
# 나쁨 - 마크다운 테이블 대신 코드로 라우팅 로직
if (intent.includes('deploy')) { agent = opsAgent; }
라우팅을 CLAUDE.md 마크다운 테이블에 선언적으로 유지하세요. 검사, 편집, 디버깅이 가능합니다.
모범 사례
-
CLAUDE.md는 200줄 미만이고 컨텍스트 창에 맞습니다. - 각 에이전트 파일은 100줄 미만이고 한 도메인에 집중합니다.
-
data/는 민감한 로그에 대해 git-ignored되고 결정 및 사양에 대해 git-tracked됩니다. - 명령어는 명령형 이름을 사용합니다:
/run-daily-sync대신/daily-sync - 로그는 추가 전용입니다. 과거 일일 로그를 편집하지 마세요.
- 모든 에이전트에는 읽는 파일을 정의하는
Memory Scope섹션이 있습니다. - 반영은 모든 세션이 끝날 때 작성됩니다.
- 예약된 작업은 Claude Code의 세션 cron이 아닌 외부 cron(LaunchAgent, systemd, pm2)을 사용합니다.
- 비용 추적:
data/logs/<날짜>-costs.json에 세션당 API 지출 기록 - 하나의 프로젝트 = 하나의 Agentic OS. 관련 없는 프로젝트 간에 단일
CLAUDE.md를 공유하지 마세요.