당신의 사이드 프로젝트에 운영팀이 생겼습니다.
프로젝트를 지켜보고 점점 더 똑똑해집니다. Level 0에서 시작하세요. 신뢰가 쌓이면 올리세요.
Claude Code 필수. 모든 명령어(
/ooda-setup,/evolve등)는 Claude Code 슬래시 커맨드입니다.
한국어 | English
OODA-loop는 Claude Code 기반의 자율 AI 에이전트 프레임워크입니다. 코드베이스를 감시하고, 무엇이 중요한지 학습하고, 당신이 자는 동안 행동합니다. Boyd의 OODA 사이클(관찰, 정향, 결정, 행동)을 기반으로, 혼자 개발하는 사람에게 10배 큰 팀의 운영 역량을 부여합니다. 프로덕션 시스템(fwd.page)에서 추출한 아키텍처를 기반으로 합니다. 점진적 자율 레벨, 신뢰도 임계값, 한 파일로 끄는 킬 스위치, 에이전트가 절대 수정할 수 없는 보호 경로를 갖추고 있습니다.
설치 (택 1):
# 방법 A: Claude Code 플러그인 (권장)
/plugin marketplace add mataeil/OODA-loop
/plugin install ooda-loop
# 방법 B: Git으로 전역 설치
git clone https://github.com/mataeil/OODA-loop.git ~/.ooda-loop
~/.ooda-loop/install.sh프로젝트에 설정:
cd your-project/
/ooda-setup # 스택 자동 감지, config 생성
/evolve # 첫 사이클 (관찰만 — 아무것도 수정 안 함)
/ooda-status # 결과 확인/ooda-setup이 프로젝트에 config.json과 agent/state/를 생성합니다. 관찰 중에는
소스 코드를 절대 수정하지 않습니다.
아무것도 바꾸지 않습니다. Level 0은 관찰만. Level 3에서 PR을 엽니다.
1950년대, 전투기 조종사 John Boyd는 왜 어떤 조종사는 공중전에서 이기고 어떤 조종사는 지는지 연구했습니다. 답은 더 빠른 비행기나 더 좋은 무기가 아니었습니다. 의사결정 사이클이었습니다: 관찰(Observe), 정향(Orient), 결정(Decide), 행동(Act).
OODA를 더 빨리 돌리는 조종사가 우위를 점했습니다. 하지만 Boyd의 더 깊은 통찰은 단순한 속도가 아니었습니다 -- 바로 정향(Orient) 단계였습니다. 정향은 세계에 대한 멘탈 모델을 구축하는 곳입니다. 과거의 모든 교전, 모든 교훈, 인식된 모든 패턴이 여기서 수렴합니다. 더 나은 세계 모델을 가진 조종사가 압박 속에서도 더 나은 판단을 내립니다.
OODA는 한 번 걸어가는 순서도가 아닙니다. 지속적인 피드백 루프입니다:
+----------+ +-----------+
+------>| OBSERVE |------->| ORIENT |------+
| +----------+ +-----------+ |
| ^ | | |
| | implicit| | v
| | guidance| | +-----------+
| | | +-->| DECIDE |
| +----------+ | +-----------+
+-------+ ACT |<------+-------------|
+----------+
정향은 단순히 결정에 정보를 넘기는 것이 아닙니다. 다음에 무엇을 관찰할지를 재구성합니다. 의식적 사고를 건너뛸 수 있는 암묵적 가이드라인을 만듭니다 -- 숙련된 조종사가 의식적으로 생각하기 전에 반응하는 것처럼. 매 사이클이 모델을 날카롭게 합니다. 매 결과가 믿음을 업데이트합니다.
이것이 OODA를 상태 머신이나 예약 스크립트와 구분짓는 것입니다. 크론잡은 같은 로직을 영원히 반복합니다. OODA 루프는 진화합니다.
대부분의 자동화는 뇌가 없습니다. 100일째에도 1일째와 같은 스크립트를 돌립니다. 지난주 뭐가 잘됐는지 모릅니다. 환경이 바뀌어도 조정하지 않습니다. 기억도, 판단도, 자신이 운영하는 세계에 대한 모델도 없습니다.
OODA-loop가 다른 이유는 정향(Orient) 때문입니다 -- 에이전트가 세계 모델을 구축하고 업데이트하는 단계입니다. 매 사이클 후 에이전트는 어떤 도메인이 관심을 필요로 하는지(신뢰도 점수), 어떤 패턴이 관찰 전반에서 나타나는지(교차 도메인 상관), 과거 결정이 무엇으로 이어졌는지(결과 추적)를 알게 됩니다.
Adaptive Lens. 관찰 스킬은 정적이지 않습니다. 매 사이클, 엔진은 관찰 결과를
분석하고 도메인별 lens.json에 개선을 제안합니다 -- 학습된 임계값, 집중 항목,
발견된 시그널. 새로운 학습은 조심스럽게 시작하고(신뢰도 0.3), 반복 검증 후에만
활성화됩니다(0.6). 반증하는 증거는 확인하는 증거보다 2배 빨리 나쁜 학습을
제거합니다(+0.1 vs -0.2). 50번째 사이클에서는 1번째 사이클이 볼 줄도 몰랐던
패턴을 잡아냅니다. 설계부터 안티프래질합니다.
3단계 메모리. 작업 메모리(최근 20개 결정)가 주간 에피소드 요약(52주)으로 흐르고, 이것이 영구적인 원칙으로 증류됩니다. 에이전트는 무슨 일이 있었는지만 기억하는 것이 아니라 -- 무엇이 중요한지를 학습합니다.
크론잡은 심장박동을 줍니다. OODA-loop는 두뇌를 줍니다.
OODA-loop는 특정 스택에 묶인 코드 생성기가 아닙니다. AI가 사고하는 프레임워크 입니다 -- 에이전트가 관찰하고, 학습하고, 행동하는 구조화된 방식입니다. 테스트 출력을 읽고, 엔드포인트를 체크하고, 이슈를 스코어링합니다. 어떤 언어로 개발하든 상관없습니다.
테스트 커맨드, git repo, 또는 HTTP 엔드포인트가 있는 프로젝트라면 사용할 수 있습니다. 웹 서버, CLI 도구, 라이브러리, 모노레포 — 루프는 가진 것에 맞춰 적응합니다.
9개 환경에서 검증:
| 스택 | 프로젝트 유형 | 테스트 프레임워크 |
|---|---|---|
| Python + FastAPI | REST API | pytest + pytest-cov |
| Python (프레임워크 없음) | 라이브러리 / 패키지 | pytest + pytest-cov |
| Go + net/http | HTTP 서버 | go test |
| Node.js + Express | REST API | Jest + supertest |
| Node.js | CLI 도구 (서버 없음) | Jest |
| TypeScript | CLI 도구 | ts-jest |
| React + Vite | SPA | Vitest |
| Rust | CLI 도구 | cargo test |
| Bun + Hono | HTTP 서버 | bun:test |
당신은 사이드 프로젝트를 운영하고 있습니다. 유료 사용자가 몇 명인 SaaS일 수도 있고, 지난달 런칭하고 잊어버린 API일 수도 있습니다. 본업이 있거나, 프로젝트가 세 개이거나, 둘 다이거나. 헬스 엔드포인트가 6시간째 503을 리턴하고 있는데 자고 있어서 모릅니다.
DevOps 팀이 없습니다. 온콜 로테이션도 PagerDuty 구독도 없습니다. Git 레포 하나, 한 번 설정한 CI 파이프라인, 그리고 아마 괜찮을 거라는 막연한 감각이 있을 뿐입니다.
OODA-loop는 당신을 위한 것입니다.
경쟁이 치열한 시장에서 모니터링보다 빠르게 움직여야 하는 인디 해커를 위한 것입니다. 한 명은 코드를 쓰고 한 명은 카피를 쓰는 2인 스타트업에서 아무도 매일 아침 백로그를 리뷰할 시간이 없는 팀을 위한 것입니다. 자신이 보지 않는 동안에도 프로젝트가 성장하고 개선되기를 원하는 개발자를 위한 것입니다.
이것은 엔터프라이즈 플랫폼이 아닙니다. 대시보드 SaaS도, 시트 기반 가격도, 영업 전화도 없습니다. 레포 안에 살고, Claude Code 안에서 실행되고, 한 사이클씩 신뢰를 쌓아가는 프레임워크입니다.
- 코드 생성 에이전트가 아닙니다 (Devin, Cursor Agent) -- 그것들은 명령에 따라 코드를 씁니다. 이것은 스스로 관찰하고, 학습하고, 운영합니다.
- CI/CD 파이프라인이 아닙니다 -- 이것은 무엇을 할지 결정합니다. 어떻게 실행할지가 아닙니다.
- 모니터링 SaaS가 아닙니다 (Datadog, PagerDuty) -- 레포 안에 살고, 하루 ~$1-2, 구독 없음.
- 크론잡이 아닙니다 -- 크론잡은 같은 스크립트를 영원히 반복합니다. OODA-loop는 매 사이클 진화합니다.
Day 1. 플러그인을 설치하고 프로젝트에서 /ooda-setup을 실행합니다. 스택을
감지하고, 모니터링할 도메인을 제안하고, 설정 파일을 생성합니다. 첫 /evolve는
관찰 전용입니다 -- 보고, 발견한 것을 기록합니다.
/ooda-status
Cycle: #1 | Level: 0 (Just watching)
Domains scanned: 3
service_health — confidence 0.70
test_coverage 87.2% confidence 0.70
backlog 12 open confidence 0.70
Actions: 0 pending | PRs: 0
HALT: inactive
그게 전부입니다. 봤고, 본 것을 적었습니다. 읽고 넘어갑니다.
Day 3. 세 번째 사이클. 관찰이 서로를 확인하면서 신뢰도가 올라갑니다. 레벨을 1로 올립니다. 이제 두 개의 도메인을 감시하고 커버리지가 떨어지면 알려줍니다. 여전히 코드 변경은 없습니다 -- 더 날카로운 관찰뿐.
Day 7. 레벨 2. 전체 백로그 추적, 이슈 스코어링, 리포트. Adaptive Lens가
학습을 시작했습니다 -- 항상 통과하는 헬스 체크는 우선순위가 내려가고, 불안정한
테스트 패턴은 더 빨리 잡힙니다. OODA-loop가 시장 분석 설정을 제안합니다:
/ooda-skill create scan-market.
Day 30. 레벨 3. 다음 사이클에서 OODA-loop는 가장 높은 점수의 백로그 항목을 골라 코드를 작성하고, 테스트를 돌리고, Draft PR을 엽니다. PR은 작습니다 -- 최대 20개 파일, 500줄, 설정으로 강제됩니다. 커피 마시면서 리뷰합니다. 루프는 새벽 3시에 돌아갔고, 당신이 아침 9시에 알아챘을 것을 4시간 먼저 처리했습니다.
HALT 파일은 여전히 있습니다. 쓸 필요가 없었을 뿐입니다.
자가발전 실증. 9개 스택(Python, Go, Node, React, Rust, Bun)에 걸친 60회 샌드박스 사이클에서 에이전트는 36개 PR을 생성했고, 컴파일/테스트 실패는 0건 이었습니다. 한 실행에서 Python 라이브러리의 테스트가 15개에서 91개로, 커버리지가 91%에서 100%로 증가했으며, 25개 기능이 구현되었습니다 -- 기존 코드의 수학적 패턴을 스스로 인식하여 제안한 함수 포함. 에이전트 자신의 구현이 커버리지 하락을 유발하자, 하락을 감지하고 기존 어떤 작업보다 높은 우선순위로 수정 작업을 자동 생성하여 다음 사이클에서 해결했습니다. 최종 단계에서 액션의 65%는 원래 백로그가 아닌 에이전트가 스스로 발견한 것이었습니다. 루프는 체크리스트를 실행하는 것이 아닙니다. 자기 행동의 결과를 관찰하고 적응합니다.
/evolve 실행마다 하나의 완전한 OODA 사이클을 수행합니다:
- 안전 -- HALT 파일 확인. 사이클 간격 확인. 락 획득.
- 관찰(Observe) -- 모든 도메인 상태, GitHub PR/이슈, 외부 시그널 읽기. Adaptive Lens 로드.
- 정향(Orient) -- 패턴 감지, 신뢰도 업데이트, 액션 큐와 PR 결과 동기화, 세계 모델 요약 작성.
- 결정(Decide) -- 모든 도메인 스코어링. 긴급 시그널과 목표 기여도 적용. 최고 점수 선택. 신뢰도 임계값 게이트.
- 행동(Act) -- 선택된 스킬 실행. 신뢰도가 높으면 체인 실행. PR 리스크 티어 처리(자동 머지 / 수동 배포 / 사람 리뷰).
- 반성(Reflect) -- 스킬 갭 업데이트, 메모 작성, 액션 추출, Adaptive Lens 업데이트, 메모리 캐스케이드.
도메인 스코어링 (v1.2.0): score = staleness + dampened_alert + (목표 × 0.3) + (신뢰도 × 0.2) + 메모 + 밸런스_페널티
여기서 메모 = score_adjustments[도메인] + Σ interventions[].delta.
Staleness는 대수 곡선을 기본 사용합니다. Alert 감쇠기가 도메인 독점을 방지합니다. 엔트로피 밸런스 페널티가 건강한 도메인 순환을 보장합니다. 메모는 v1.2.0부터 1회성 score_adjustments와 다중 사이클 interventions를 합산합니다 (CONCEPTS.md Memo Interventions 참조).
전체 용어집, 아키텍처 다이어그램, 공식 상세는 CONCEPTS.md를 참조하세요. v1.2.0 릴리스 노트는 CHANGELOG.md를 보세요.
5개 도메인 스킬, 4개 위저드, 오케스트레이터:
| 명령어 | 단계 | 기능 |
|---|---|---|
/scan-health |
관찰 | 헬스 엔드포인트 모니터링, 이상 감지 |
/check-tests |
탐지 | 테스트 실행, 커버리지 추세 추적 |
/plan-backlog |
전략 | GitHub 이슈 RICE 스코어링 |
/run-deploy |
실행 | 배포 워크플로우 트리거 |
/dev-cycle |
지원 | 전체 구현 파이프라인 |
/ooda-setup |
위저드 | 3단계 프로젝트 설정 |
/ooda-config |
위저드 | 설정 조회 및 수정 |
/ooda-status |
위저드 | 상태 대시보드 |
/ooda-skill |
위저드 | 도메인 스킬 생성/비활성화/활성화 |
/evolve |
메타 | 하나의 완전한 OODA 사이클 실행 (/loop 4h /evolve) |
도메인 상태. 설정의 각 도메인은 active(매 사이클 실행), available(설정됨
but 스킬 미생성), disabled(비활성화) 중 하나입니다. available 스킬은 조용히
건너뜁니다 -- 에러 없이, 중단 없이.
스킬 생성. /ooda-skill create scan-market을 실행하고 프로젝트에 대한
3-5개 질문에 답하면 됩니다. 위저드가 Adaptive Lens가 통합된 완전한 프로젝트 맞춤
SKILL.md를 생성합니다. 시장 조사, UX 감사, 경쟁사 모니터링 템플릿이
templates/skill-generators/에 포함되어 있습니다.
레벨 0에서 시작합니다. 관찰이 신뢰할 만해지면 올립니다.
| 레벨 | 이름 | 동작 |
|---|---|---|
| 0 | 지켜보기만 | 1개 도메인. 관찰 전용. PR 없음. |
| 1 | 관찰 + 테스트 | 2개 도메인. 커버리지 추적 추가. |
| 2 | 전체 관찰 | 모든 도메인. Draft PR(사람이 머지). 리포트, 스코어링, 렌즈 학습. |
| 3 | 자율 운영 | 구현 활성화. 전체 PR. 저위험 변경 자동 머지. |
/ooda-config level 2
OODA-loop는 기본적으로 안전합니다. 레벨 0은 PR을 만들 수 없습니다. 레벨 3은 의도적 선택이 필요합니다.
- HALT 파일 --
touch agent/safety/HALT로 모든 것을 즉시 정지. 삭제하면 재개. - 보호 경로 --
agent/safety/*,skills/evolve/*,agent/contracts/*는 에이전트가 수정할 수 없음. 자기 자신의 규칙을 다시 쓸 수 없음. - 신뢰도 게이트 -- 0.6 미만 신뢰도의 행동은 건너뛰거나 다운그레이드.
- PR 제한 -- PR당 최대 20개 파일, 500줄. 설정으로 강제.
- 첫 사이클 관찰 전용 -- 첫 실행에서는 행동 없이 관찰만.
- 스킬 허용목록 -- 등록된 스킬만 호출 가능.
- 락 타임아웃 -- 동시 실행 락 30분 후 자동 만료(
lock_timeout_minutes설정 가능). 크래시로 인한 정체된 락 자동 정리. - 비용 원장 -- 일일 API 비용
cost_ledger.json에 추적.cost.daily_limit_usd($10 기본값) 도달 시 강제 정지, 80%에서 경고. 매일 00:00 UTC 초기화. 원장 파일 누락 시 안전측 정지(fail-closed). - Adaptive Lens 안전 -- 나쁜 학습은 좋은 학습보다 2배 빨리 소멸. 렌즈 손상 시 기본 동작으로 폴백.
전체 위협 모델과 안전 아키텍처는 SECURITY.md를 참조하세요.
/ooda-setup이 config.json을 자동 생성합니다. 수동 편집은 /ooda-config를
사용하거나 파일을 직접 수정하세요. 주요 섹션: project(이름, 로케일, 타임존), domains(모니터링 대상, 가중치, 스킬, 상태), safety(HALT 경로,
PR 제한, 허용목록, lock_timeout_minutes), confidence(초기값, 머지 부스트,
리젝트 패널티), scoring(공식 파라미터), progressive_complexity(현재 레벨),
signals(긴급 시그널 임계값), memory(보존, 감쇠, 액션 큐 감쇠),
notifications(Telegram, $ENV_VAR 방식), cost(일일 한도, 경고 임계값).
전체 스키마는 config.example.json을 참조하세요.
두 개의 프로덕션 배포에서 지속적으로 실전 데이터를 수집하여 업스트림 개선에 반영합니다:
| 배포 | 도메인 | 사이클 | PR | 성공률 |
|---|---|---|---|---|
| fwd.page | URL 단축기 | 152+ | 28 (24 머지, 86%) | 100% |
| Lynceus | 국정감사 자동화 | 119+ | 0 (Level 2) | 100% |
v1.1.0에서 초기 프로덕션 데이터(209 사이클) 기반 수정사항:
- 설계됐으나 미작동 기능 7개 복구 — episode, principles, adaptive lens, contrarian, cost ledger, chain, skill gaps
- 스코어링 독점 — 단일 도메인이 36% 차지. 대수 staleness + 엔트로피 페널티 + alert 감쇠로 해결
- 41사이클 관찰 포화 — circuit breaker가 5회 경고, 10회 부스트, 15회 정지
- 신뢰도 정체 — Level < 3에서 관찰 기반 micro-adjustments로 고정 방지
v1.2.0에서 추가 프로덕션 데이터(152 + 119 사이클) 기반 수정사항:
- Orient 레이어가 실제로 학습함 — principles 임계값 완화 (Jaccard 0.8 → 0.5, 횟수 3 → 2) + 클러스터 fallback. Lynceus의 2개 에피소드에서도 principle 추출 가능.
- Memo가 능동적 개입으로 승격 —
memos.json.interventions[]가 Lynceus 수동 +1.0 / −10.0 패턴을starvation/monopoly_breaker자동 기록으로 형식화. 다중 사이클 지속. - Cost ledger 무결성 게이트 — fwd의 13일 cost 추적 공백이 재발 불가능. Step 6-C8이 누락된 entry를 auto-patch하고
learning_loop_breakskill_gap 발행. - Lens 사전 초기화 — fwd의 152 사이클 lens 부재 원인은 커스텀 observe 스킬이 init helper를 호출하지 않아서. 이제 Step 1-A에서 모든 active 도메인에 대해 무조건 생성.
- 프리미티브 업스트림 승격 — Lynceus
weight_presets→season_modes배선; Lynceusactive_context→ 1급 config 키; fwdfocus_rotation→config.domains.{name}.rotation. fwd의 하드코딩된service_health × 2.0은season_modes.modes.default.weight_overrides로 통합. - Orient Health 대시보드 —
/ooda-status --orient가 episodes / principles / lens coverage / chain 실행 / 활성 interventions / skill gaps를 한눈에 표시.
fwd.page와 Lynceus는 v1.2.0 작업에서 수정하지 않습니다. 이들은 참고 데이터 소스이며, 모든 변경은 프레임워크에 landing하여 다음 프로젝트가 이 개선을 기본으로 얻도록 합니다.
기여를 환영합니다: 새로운 도메인 스킬, 스코어링 개선, 인테그레이션, 문서. 스킬 작성 가이드, 3-tier 기여 모델(Skills / Docs / Core), 코드 스타일 규칙은 CONTRIBUTING.md를 참조하세요.
/plugin marketplace add mataeil/OODA-loop
/plugin install ooda-loop
cd your-project && /ooda-setup
사이드 프로젝트에 두뇌를 주세요. Level 0에서 시작합니다. 관찰만 합니다.
MIT -- LICENSE 참조