Ko&Clo · Enterprise — 실제 구현 코드는 비공개 저장소입니다.
이 저장소는 설계 의사결정과 실행 과정을 정리한 케이스 스터디입니다.
AI Native 개발환경으로 전환하기 위해 Harness Engineering 기법으로 AI 인프라를 설계하고,
각각의 기능을 노드화해 동시에 관리·개선할 수 있는 Graph Engineering 시스템을 설계·구축했습니다.
| 53 | 69 | 7 | 46 |
|---|---|---|---|
| Sub-Agents | Memory Files | Guard Hooks | Permission Rules |
- Harness Engineering — 권한 규칙 46개와 훅 7개가 도구 실행 전에 허용 범위를 결정
- Loop Engineering — '된 것 같다'가 아니라 모든 스토리가 리뷰어 검증을 통과할 때까지 반복
- Graph Engineering — 서브탭 1개 = 노드 1개 = 에이전트 1개, 53개 노드가 각자 도메인·아키텍처·피드백 메모리를 보유
- 노드마다 소유자가 하나뿐이라 기능 수정·추가를 충돌 없이 병렬로 수행
| 축 | 역할 |
|---|---|
| 01 Harness | 환경을 제어 — 권한 티어, 차단 훅, 예산 상한이 걸린 컨텍스트 주입 |
| 02 Loop | 검증될 때까지 반복 — 스토리 단위로 순회하고 리뷰어 승인 후에만 완료 |
| 03 Graph | 제품을 노드로 분해 — 서브탭 1개에 에이전트 1개, 공유 자산은 명시적 엣지 |
모든 프롬프트는 같은 경로를 지납니다. 진입 시 컨텍스트가 주입되고, 도구 호출마다 가드가 걸리며, 종료 시 학습이 통합됩니다.
Prompt ──▶ memory-recall ──▶ Skill Router ──▶ 53 Sub-Agents ──▶ PreToolUse ──▶ Codebase
user UserPromptSubmit 21 skills 1 subtab nas·danger read · edit
intent IDF match · 4K 27 commands : 1 agent ·testfile · verify
│ block = exit 2 │
▼ ▼
File Memory Stop hook
69 files · domain/service/meta consolidate · /learn
Harness — deny 14 · ask 32 · PreToolUse hard block · time-boxed gates
에이전트가 딛고 서는 모든 것이 레포에 버전 관리됩니다 — 개발자별 세팅도, 숨은 상태도 없습니다.
.claude/
├── settings.json permission tiers + hook wiring
├── agents/ 53 files one per product subtab
├── skills/ 21 dirs identify → delegate → verify
├── commands/ 27 files /vmd /payrate /danger /learn …
├── hooks/ 7 files guards + memory lifecycle
├── memory/ 69 files
│ ├── meta/ agent_kernel.md — shared rules
│ ├── domain/ business terms + *-feedback.md
│ ├── service/ file ↔ API ↔ DB architecture maps
│ └── MEMORY.md index
├── context-pack.template.md work-surface pinning
└── .danger-unlock time-boxed gate (expiry epoch)
환경을 6개 하네스로 나눠 설계하고, 각각을 따로 구축·감사했습니다.
Context
CLAUDE.md 정책 + 3계층 메모리(meta / domain / service) + 예산 상한이 걸린 자동 주입.
Permission
settings.json의 deny / ask 티어, 그리고 권한 계층 아래에서 한 번 더 막는 훅.
Tool
스킬이 라우팅, 에이전트가 소유, 커맨드가 노출 — 트리거 키워드 충돌은 경계로 명시.
Subagent & Worktree
파일시스템 격리를 위한 git worktree 4개. worktree 간 메모리 공유 한계는 숨기지 않고 문서화.
Verification
회귀 검증 체크리스트를 스킬에 내장. 테스트 파일 생성은 자유, 커밋만 차단.
Debugging
시크릿 값을 한 번도 열지 않고 만든 환경 변수 scope matrix.
| 14 | 32 | 2 |
|---|---|---|
| deny | ask | gates |
Deny — 하드 거부
git push, DROP / TRUNCATE, rm -rf /, .env·secrets 읽기·수정.
승인해도 실행되지 않습니다.
Ask — 확인 필수
git commit / merge / rebase, docker compose 라이프사이클, 마이그레이션, chmod, sudo.
Gates — 시한부 승급
/nas on, /danger on 은 만료 시각(epoch)이 든 게이트 파일을 엽니다 — 권한을 영구가 아니라 기간으로 부여합니다.
Secrets
.env는 권한 계층에서 읽기 거부. 환경 매트릭스는 각 변수가 어디에 선언됐는지만 기록하고 값은 적지 않습니다.
4개 라이프사이클 이벤트에 훅 7개. 차단 훅은 exit 2로 막고, 메모리 훅은 fail-open이라 세션을 절대 멈추지 않습니다.
| Hook | Event | 역할 |
|---|---|---|
memory-recall |
UserPromptSubmit | 프롬프트와 메모리 파일을 IDF로 점수화해 최적 매치를 4,000자 예산 안에서 주입 |
nas-guard |
PreToolUse | 운영 NAS 마커가 포함된 명령은 게이트가 열려 있지 않으면 차단 |
danger-guard |
PreToolUse | 비가역 명령 차단 — force push, reset --hard, docker prune, SQL drop / truncate |
testfile-commit-guard |
PreToolUse | 테스트 파일 생성은 자유, 커밋만 차단. 지시하지 않은 테스트 859줄이 기능 커밋에 섞인 사고 이후 도입 |
init-sql-mirror |
PostToolUse | 세션에서 실행된 DDL/DML을 감지해 스키마 정본인 init.sql에 반영하도록 강제 |
sync-plugins |
PostToolUse | 플러그인 정의 수정 후 동기화 유지 |
memory-consolidate |
Stop | 세션에 지적이 있었는데 기록이 없으면 종료 전 1회 환기 |
개발은 레포 단위가 아니라 노드 단위로 일어납니다.
노드 하나 = 서브탭 하나 = 전담 에이전트 하나 — 변경이 경계 밖으로 새지 않습니다.
Tab (skill router)
│
┌───────────────┼───────────────┐
▼ ▼ ▼
node · subtab A node · subtab B node · subtab C
agent + memory agent + memory agent + memory
└───────────────┼───────────────┘
한 메시지로 위임 → 병렬 실행
│
shared asset
edge — report to main
Node
에이전트 53개가 서브탭과 1:1 대응하고, 각 노드가 자기 domain·architecture·feedback 메모리를 갖습니다.
Parallelism
독립 노드는 단일 메시지로 한 번에 위임 — 여러 기능을 동시에 충돌 없이 수정합니다.
Edge
공유 산식·API 응답 키·DB 테이블이 엣지입니다. 엣지를 건드리면 메인 세션에 보고해야 합니다.
Growth
새 노드와 엣지는 agent-blueprint가 정본 노드로부터 생성 — 매번 새로 고안하지 않습니다.
| 영역 | 기술 |
|---|---|
| Runtime | Claude Code · Sub-Agents · MCP |
| Harness | Hooks (bash / Python) · settings.json · Gate files |
| Knowledge | Markdown Memory · IDF Retrieval · Feedback Ledger |
| Isolation | Git Worktrees · Docker dev/prod |
Safety
파괴적·운영 접근 명령을 승인 계층 아래에서 차단하고, 접근은 만료되는 게이트로만 부여합니다.
Repeatability
새 탭의 에이전트 시스템을 매번 새로 고안하지 않고 정본 구조로부터 생성합니다.
Knowledge
지적이 번호 붙은 피드백으로 남고 이후 세션에 자동으로 다시 주입됩니다.
Discipline
문서의 모든 강제 주장을 코드와 대조 검증하고, 공백은 서술이 아니라 수정으로 해소했습니다.