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 | 코드, 아키텍처, 디버깅 | 사용자가 "build", "fix", "refactor" 말함 |
| @writer | 문서, 콘텐츠, 이메일 | 사용자가 "write", "draft", "blog" 말함 |
| @researcher | 연구, 분석, 사실 확인 | 사용자가 "research", "analyze", "compare" 말함 |
| @ops | DevOps, 배포, 인프라 | 사용자가 "deploy", "CI", "server" 말함 |
## 라우팅 규칙
1. 사용자 요청에서 의도 키워드 파싱
2. 에이전트 레지스트리 트리거 열과 일치
3. `agents/<name>.md`에서 해당 에이전트 파일 로드
4. 전체 컨텍스트와 함께 실행 위임
5. 결과를 종합하여 사용자에게 제시
## 모델 정책
- 기본 모델: 저장소 또는 하네스 기본값 사용
- @dev 작업: 복잡한 아키텍처의 경우 더 높은 추론 모델 선호
- @researcher 작업: 구성된 연구 가능 모델과 승인된 검색 도구 사용
- 비용 상한: 프로젝트의 구성된 지출 임계값을 초과하기 전에 경고
핵심 원칙
커널은 작고 선언적이어야 합니다. 라우팅 로직은 코드가 아닌 일반 마크다운 테이블에 있습니다. 이렇게 하면 시스템을 디버깅 없이 검사하고 편집할 수 있습니다.
전문 에이전트
각 에이전트는 agents/ 디렉터리의 독립적인 마크다운 파일입니다. Claude는 작업을 라우팅할 때 관련 에이전트 파일을 로드합니다.
에이전트 정의 형식
# @dev - 소프트웨어 엔지니어
## 정체성
당신은 시니어 소프트웨어 엔지니어입니다. 깨끗하고, 테스트되었으며, 프로덕션 수준의 코드를 작성합니다.
간단한 해결책을 선호합니다. 요구 사항이 모호할 때 명확한 질문을 합니다.
## 메모리 범위
- `data/projects/<current-project>.md`에서 컨텍스트 읽기
- `data/decisions/`에서 아키텍처 결정 읽기
- 실행 로그를 `data/logs/<date>[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/<date>.md`에 추가
표준 명령어 세트
| 명령어 | 목적 |
|---|---|
/daily-sync | 아침 브리핑: 상태, 차단 항목, 우선 순위 |
/outreach | 아웃리치 워크플로우 실행 (이메일, LinkedIn 등) |
/research <topic> | 인용 추적을 통한 심층 연구 |
/apply-jobs | 대상 역할에 맞게 이력서 + 자기소개서 맞춤화 |
/analytics | Stripe, GitHub 또는 사용자 정의 소스에서 지표 가져오기 |
/interview-prep | 플래시카드 또는 모의 면접 질문 생성 |
/decision <topic> | 장단점 및 선택한 경로로 결정 기록 |
명령어 활성화
명령어 파일을 .claude/commands/<command-name>.md에 배치하세요. Claude Code가 자동으로 발견합니다. 사용자는 /<command-name>으로 호출합니다.
지속적 메모리
메모리는 파일 기반입니다. 벡터 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 키 대기 중 (2024-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 Timer
# ~/.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"
}
}
서술형 콘텐츠를 위한 마크다운
사람이 읽는 모든 항목(결정, 로그, 연구 노트, 연락처 기록)에는 마크다운을 사용하세요.
스키마 진화
기존 필드의 이름을 절대 변경하지 마십시오. 새 필드를 추가하고 이전 필드를 사용 중단(deprecated)으로 표시하세요:
{
"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-무시, 결정 및 사양의 경우 git-추적합니다 - 명령어는 명령형 이름을 사용합니다:
/run-daily-sync가 아닌/daily-sync - 로그는 추가 전용입니다. 과거의 일일 로그는 절대 편집하지 마십시오
- 모든 에이전트는 읽는 파일을 정의하는
메모리 범위섹션이 있습니다 - 반성은 모든 세션 종료 시 작성됩니다
- 예약 작업은 Claude Code의 세션 cron이 아닌 외부 cron(LaunchAgent, systemd, pm2)을 사용합니다
- 비용 추적:
data/logs/<date>-costs.json에 세션별 API 지출 기록 - 하나의 프로젝트 = 하나의 Agentic OS. 관련 없는 프로젝트 간에 단일
CLAUDE.md를 공유하지 마십시오.