AI 개발 시스템 — LightHarness

AI Development System — LightHarness

4-Tier 라우팅 + 모듈형 스크립트 기반 에이전트 오케스트레이터

Agent Orchestrator on 4-Tier Routing + Modular Script Layer

2026-04-16 Queue 머지 · 14 감사 카테고리 · 모듈형 스크립트 레이어 Queue Merge · 14 Audit Categories · Modular Script Layer Claude Pro 기반 Built for Claude Pro

Agentic AI 개념 Agentic AI Concepts MCP 생태계 MCP Ecosystem AI 개발 시스템 (현재) AI Dev System (current)

1. 개요

1. Overview

LightHarness는 Claude Pro 안에서 소·중규모 작업을 효율적으로 처리하는 경량 에이전트 팀 프레임워크다. 4-Tier 라우팅 위의 워크플로우 오케스트레이터로, 슬래시 커맨드로 동작한다.

LightHarness is a lightweight agent team framework for efficiently handling small-to-medium tasks within Claude Pro. It acts as a workflow orchestrator on top of 4-Tier routing, operated via slash commands.

핵심 원칙: cloud(Claude) 사용을 최소화하고 판단·조율만 맡기며, 실작업은 Tier 2~4에 위임한다. 기계적 작업(git, 파일 I/O, YAML, 볼트 동기화)은 Python 모듈이 병렬로 처리한다.

Core principle: minimize direct cloud (Claude) usage — only judgment and coordination. Mechanical work (git, file I/O, YAML, vault sync) is handled by Python modules running in parallel.

2. 4-Tier 구조

2. 4-Tier Architecture

Tier 1

Claude Code

판단·조율, 슬래시 커맨드 처리, 아키텍처 결정, 결과 통합

Judgment, coordination, slash commands, architecture decisions

Mac Web Codespaces

Tier 2

Gemini

대규모 코드 분석, 감사, 린트. subagent 또는 API로 동작

Large codebase analysis, auditing, linting. Runs as subagent or API.

Mac Web Codespaces

Tier 3

Groq (70B)

플래닝, 리뷰, 분석, 코드 검증. Tier 2 실패 시 에스컬레이션 대상

Planning, review, analysis, code verification. Escalation target when Tier 2 fails.

Mac Web

Tier 4

로컬 LLM (7B)

Local LLM (7B)

단순 반복 전용: 커밋 메시지, 포맷 변환, 보일러플레이트 생성

Simple repetitive tasks only: commit messages, format conversion, boilerplate

Mac only

4-Tier 구조 및 에스컬레이션 체인

4-Tier Architecture and Escalation Chain

⚠️

local 에이전트 프롬프트는 반드시 영어로 작성한다. 로컬 LLM 품질 최적화 목적. Lint RULE-2에서 자동 차단.

Local agent prompts must be in English. Optimizes local LLM output quality. Lint RULE-2 blocks violations.

2b. 모듈형 스크립트 레이어

2b. Modular Script Layer

기계적 작업(git, 파일 I/O, YAML 파싱, 볼트 동기화)은 Python 모듈이 처리한다. AI는 판단이 필요한 경우에만 개입. 모듈은 ThreadPoolExecutor로 병렬 실행된다.

Mechanical work (git, file I/O, YAML parsing, vault sync) is handled by Python modules. AI only intervenes when judgment is needed. Modules run in parallel via ThreadPoolExecutor.

Module	역할	Role	사용 스킬	Used By
`lib/paths.py`	경로 상수, 날짜 헬퍼	Path constants, date helpers	전체	All
`lib/git_ops.py`	status, diff, commit, push, 병렬 repo 스캔	status, diff, commit, push, parallel repo scan	vault-sync, gsync, rsml
`lib/vault_ops.py`	index.yaml R/W, README 패치, 타임라인, 미러	index.yaml R/W, README patch, timeline, mirror	vault-sync, gsync
`lib/todo_ops.py`	[x] 감지, 완료 항목 이동, 날짜 섹션	[x] detection, move completed items, date sections	wtodo, rsml
`lib/yaml_ops.py`	Blueprint YAML 파싱, 큐 머지 그룹 감지	Blueprint YAML parsing, merge group detection	harness-run
`lib/inventory.py`	Git·스킬·스크립트·ALoop·훅 병렬 스캔	Parallel scan: Git, skills, scripts, ALoop, hooks	vault-sync
`lib/resume_log.py`	템플릿 생성, 포인터 갱신, 자동 넘버링	Template gen, pointer update, auto-numbering	rsml

💡

Script-first 원칙: git 명령, 파일 복사, 날짜 비교, YAML 파싱에 AI를 사용하지 않는다. 17개 repo 스캔이 순차 1.5초 → 병렬 0.3초. index.yaml은 1회 읽기 → 인메모리 패치 → 1회 쓰기.

Script-first principle: No AI for git commands, file copy, date comparison, YAML parsing. 17-repo scan: sequential 1.5s → parallel 0.3s. index.yaml: 1 read → in-memory patch → 1 write.

3. 슬래시 커맨드

3. Slash Commands

하네스 & 코드 품질

Harness & Code Quality

커맨드	Command	역할
`/harness [goal]`	Blueprint YAML 설계 + Lint 자동 실행	Design Blueprint YAML + auto Lint
`/harness-run [name]`	Blueprint 실행. 인자 없으면 큐 자동 감지 (2+ → 머지 모드)	Execute Blueprint. No args → auto-detect queue (2+ → merge mode)
`/harness-check [path]`	4단계 정적 버그 감사 (scout → audit → patch → verify)	4-step static bug audit (scout → audit → patch → verify)
`/harness-debug [path]`	CRITICAL=0이 될 때까지 harness-check 반복 (최대 5라운드)	Repeats harness-check until CRITICAL=0 (max 5 rounds)
`/inspect [target] [--scope diff]`	읽기 전용 14카테고리 감사. `--scope diff`로 변경분만 감사 (CAT-14 Reuse 포함). `--help`로 스킬 비교표 출력	Read-only 14-category audit. `--scope diff` for changed files only (incl. CAT-14 Reuse). `--help` prints skill comparison
`/autodebug [target]`	런타임 디버그 루프: Audit → Fix → Deploy → Verify (백그라운드, 최대 5라운드)	Runtime debug loop: Audit → Fix → Deploy → Verify (background, max 5 rounds)
`/ci [target]`	지속적 개선: 3-Tier로 스캔 → 평가 → 리포트 → `/harness` Blueprint 자동 생성	Continuous Improvement: 3-Tier scan → assess → report → auto-generate `/harness` Blueprint
`/simplify`	변경된 코드의 재사용성·품질·효율성 리뷰 후 자동 수정	Review changed code for reuse, quality, efficiency — then fix

세션 관리

Session Management

커맨드	Command	역할
`/rsm`	세션 시작: 상태 로드 + vault 프리로드 + TODO 출력	Session start: load status + vault preload + show TODOs
`/rsml`	세션 종료: 커밋 + TODO 정리 + resume-log 저장 + vault 동기화	Session end: commit + TODO cleanup + resume-log save + vault sync
`/gsync`	프로젝트 커밋 + vault 동기화 (세션 중간) script	Project commit + vault sync (mid-session) script
`/vault-sync`	전체 로컬→볼트 동기화: 17 repo + 스킬 + 스크립트 + 미러 push script	Full local→vault sync: 17 repos + skills + scripts + mirror push script
`/wtodo`	TODO 갱신 + 완료 항목 아카이브 이동 script	Update TODO + archive completed items script

프로젝트 생성

Project Generation

커맨드	Command	역할	Role
`/maf <project> <req>`	그린필드 자동 생성: scout → 병렬 subagent(3개) → verifier → export	Greenfield auto-gen: scout → parallel subagents(3) → verifier → export

4. Blueprint YAML

/harness로 생성되는 Blueprint는 에이전트 팀의 설계도다. 두 가지 패턴 중 하나를 선택한다.

Blueprints generated by /harness are the design documents for agent teams. Choose one of two patterns.

Plan-Do-Review

분해 가능한 작업, 반복 처리에 적합

For decomposable, iterative work

planner local → worker cloud → reviewer local

Single-Agent+Helper

단순·소규모 작업, 보조만 필요한 경우

Simple/small tasks, local assist only

helper local → executor cloud

주요 필드

Key Fields

Field	설명	Description
`Template_Name`	작업 식별자 (snake_case)	Task identifier (snake_case)
`Pattern`	Plan-Do-Review 또는 Single-Agent+Helper	Plan-Do-Review or Single-Agent+Helper
`Queue.*`	머지 판단 메타: `affected_files`, `merge_group`, `dependencies`	Merge metadata: `affected_files`, `merge_group`, `dependencies`
`Agents[]`	Id, Role, Execution_Target(cloud/local), System_Prompt, Tools	Id, Role, Execution_Target(cloud/local), System_Prompt, Tools
`Workflow[]`	From → To 흐름 + Error_Policy + token_budget	From → To flow + Error_Policy + token_budget
`Defaults.Limits`	Max_Agents: 3, Max_Cloud_Steps: 10	Max_Agents: 3, Max_Cloud_Steps: 10

ℹ️

cloud 에이전트 비율 목표: 전체의 1/3 이하. 머지 모드에서 여러 cloud 단계를 1회로 병합해 추가 절감.

Cloud agent ratio target: ≤1/3 of total. Merge mode further reduces by combining multiple cloud steps into 1 call.

5. /harness-run 실행 흐름

5. /harness-run Execution Flow

/harness-run 실행 분기 및 Plan-Do-Review 패턴

/harness-run branching and Plan-Do-Review pattern

6. Queue 머지 모드

6. Queue Merge Mode

대기 중인 Blueprint들을 /harness-run 한 번에 처리. cloud 단계를 배치 내 1회로 병합해 실행 횟수를 절감한다.

Processes pending Blueprints in a single /harness-run. Merges cloud steps within a batch into 1 call to reduce executions.

배치 구성 기준

Batch Grouping Rules

#	조건	Condition	결과	Result
1	`merge_group` 값 동일	Same `merge_group`	같은 배치	Same batch
2	`affected_files` 교집합	`affected_files` overlap	같은 배치	Same batch
3	`dependencies` 관계	`dependencies` relation	같은 배치, 순서 유지	Same batch, order preserved
4	해당 없음	None	별도 배치	Separate batch

7. 코드 품질 파이프라인

7. Code Quality Pipeline

harness-check — 4-step audit

STEP 1

scout

local
프로젝트 타입 + 핵심 파일 Project type + key files

STEP 2

auditor

T2/T3
8개 카테고리 버그 분석 8-category bug analysis

STEP 3

patcher

cloud
CRITICAL / WARNING 수정 Fix CRITICAL / WARNING

STEP 4

verifier

T2/T3
4가지 회귀 검증 4 regression checks

harness-debug — 재귀 루프

harness-debug — Recursive Loop

harness-check를 CRITICAL이 0이 될 때까지 반복한다. 라운드당 cloud 1회, 최대 5라운드 = cloud 5회 상한.

Repeats harness-check until CRITICAL count reaches 0. 1 cloud step per round, max 5 rounds = 5 cloud steps cap.

inspect — 14카테고리 읽기 전용 감사

inspect — 14-Category Read-Only Audit

harness-check의 8카테고리에 6카테고리를 추가한 확장 감사. 코드를 수정하지 않고 보고서만 출력한다. CRITICAL 발견 시 /autodebug를 백그라운드로 자동 실행. --scope diff로 git 변경분만 감사하면 CAT-14(Reuse)도 자동 활성화. --help로 전체 품질 스킬 비교표 출력.

Extended audit adding 6 categories to harness-check's 8. Read-only — outputs report only. Auto-launches /autodebug in background on CRITICAL findings. Use --scope diff to audit only git changes (auto-enables CAT-14 Reuse). --help prints a comparison of all quality skills.

14개 감사 카테고리

14 Audit Categories

CAT-1

API Contract

필드명, 타입 가정 오류

Field names, type assumptions

CAT-2

Type Mismatch

인터페이스 vs 실제 응답

Interface vs actual response

CAT-3

Null Safety

optional chaining 누락

Missing optional chaining

CAT-4

Filter & Edge Case

빈 배열, 경계값 미처리

Empty arrays, boundary cases

CAT-5

Dead Code

미사용 export, 도달 불가 분기

Unused exports, unreachable branches

CAT-6

Error Handling

try/catch 누락, 에러 삼킴

Missing try/catch, swallowed errors

CAT-7 high

Security

injection, XSS, 하드코딩 비밀값

Injection, XSS, hardcoded secrets

CAT-8 high

Integration

파라미터명·env 불일치

Param name / env var mismatch

CAT-9

Performance

N+1 쿼리, 불필요한 재렌더

N+1 queries, unnecessary re-renders

CAT-10

Concurrency

레이스 컨디션, 데드락

Race conditions, deadlocks

CAT-11

Resource Leaks

미닫힌 커넥션, 파일 핸들

Unclosed connections, file handles

CAT-12

Domain Logic

비즈니스 규칙 위반, 잘못된 계산

Business rule violations, wrong calculations

CAT-13

Observability

로깅 부재, 모니터링 사각지대

Missing logging, monitoring blind spots

CAT-14 diff

Reuse

기존 유틸 중복, 헬퍼 미활용 (--scope diff 전용)

Duplicates existing util, unused helpers (--scope diff only)

autodebug — 자율 디버그 루프

autodebug — Autonomous Debug Loop

/inspect가 CRITICAL을 발견하면 자동 연계되거나, 직접 /autodebug [target]으로 실행. 백그라운드에서 성공 조건 달성까지 반복한다.

Auto-triggered when /inspect finds CRITICAL issues, or invoked directly via /autodebug [target]. Runs in background until success condition is met.

Audit

T2/T3
CRITICAL 버그 탐지 Detect CRITICAL bugs

Fix

cloud
코드 수정 Patch code

Deploy

bash
빌드 + 배포 Build + deploy

Verify

T2/T3
성공? 종료 : 1번으로 Pass? Done : goto 1

⚠️

최대 5라운드. 3라운드 이내 수렴이 일반적. 라운드당 cloud 1회 = 최대 cloud 5회. 완료 후 수정 파일이 많으면 /inspect --scope diff 제안, 구조적 문제면 /ci 제안.

Max 5 rounds. Typically converges within 3. 1 cloud step/round = max 5 cloud steps. On completion, suggests /inspect --scope diff if many files changed, or /ci for structural issues.

/ci — 지속적 개선 에이전트

/ci — Continuous Improvement Agent

디버깅이 아닌 개선에 특화. 프로젝트를 스캔해 불필요 코드, 중복, 성능 병목을 찾고, /harness Blueprint를 자동 생성한다. 실제 적용은 사용자가 /harness-run으로 나중에 수행.

Specialized in improvement, not debugging. Scans projects for dead weight, redundancy, and perf bottlenecks, then auto-generates a /harness Blueprint. User applies later via /harness-run.

Scan

Tier 3
구조·의존성 분석 Structure + deps

Assess

Tier 2
7가지 기준 평가 7-criteria eval

Report

Claude
종합 + 우선순위 Synthesize + rank

Blueprint

/harness
실행 계획 생성 Generate plan

평가 카테고리	Assessment Category	대상
P-1 Dead Weight	미사용 의존성, 고아 파일, 죽은 export	Unused deps, orphan files, dead exports
P-2 Redundancy	중복 로직, 복사-붙여넣기, 겹치는 헬퍼	Duplicate logic, copy-paste, overlapping helpers
P-3 Compactness	과도한 추상화, 불필요한 래퍼	Over-abstraction, unnecessary wrappers
P-4 Performance	느린 경로, N+1, 캐시 누락	Slow paths, N+1, missing cache
P-5 Procedure	워크플로우 위반, 일관성 없는 패턴	Workflow violations, inconsistent patterns
P-6 Dependency	과대 의존성, stdlib로 대체 가능	Oversized deps replaceable by stdlib
P-7 Structure	잘못된 위치, 순환 임포트	Misplaced files, circular imports

💡

/ci vs /inspect: /inspect는 버그를, /ci는 개선점을 찾는다. 버그가 없어도 코드는 더 좋아질 수 있다. /ci의 철학: "모든 줄은 자신의 존재를 증명해야 한다." 최근 변경분에 이슈가 집중되면 /inspect --scope diff를 제안한다.

/ci vs /inspect: /inspect finds bugs; /ci finds improvements. Code can get better even without bugs. /ci's philosophy: "Every line must earn its place." Suggests /inspect --scope diff when issues concentrate in recent changes.

8. Blueprint Lint

/harness로 Blueprint 설계 직후 자동 실행. 위반 시 실행 차단.

Auto-runs after /harness designs a Blueprint. Violations block execution.

RULE-1 Workflow To 값 = Agent Id 또는 ENDWorkflow To = Agent Id or END
RULE-2 local 에이전트 프롬프트에 한글 없음No Korean in local agent prompts
RULE-3 cloud 비율 ≤ 0.5Cloud ratio ≤ 0.5
RULE-4 모든 Workflow step에 Error_PolicyEvery step has Error_Policy
RULE-5 Queue.affected_files 비어있지 않음Queue.affected_files not empty

9. 세션 핸드오프

9. Session Handoff

세션 간 컨텍스트를 유지하는 resume-log 시스템. 날짜 기반 파일명 resume-log-YYYYMMDD-NN.md을 사용한다.

Resume-log system for cross-session context. Uses date-based filenames: resume-log-YYYYMMDD-NN.md.

커맨드	Command	동작
`/rsm`	최신 resume-log 로드 → 상태 출력 → vault 프리로드 (index.yaml) → TODO 표시	Load latest resume-log → show status → vault preload (index.yaml) → show TODOs
`/rsml`	커밋 → TODO 정리 → resume-log 저장 → vault 동기화 → GitHub push	Commit → TODO cleanup → save resume-log → vault sync → GitHub push
`/rsml -l`	resume-log만 저장 (git/TODO/sync 스킵)	Save resume-log only (skip git/TODO/sync)

ℹ️

/rsm 시작 시 vault index.yaml을 L0 프리로드해 현재 프로젝트의 스택·상태·관련 문서를 즉시 파악한다.

/rsm preloads vault index.yaml (L0) at session start to instantly identify current project's stack, status, and related docs.

10. 실사용 예

10. Real Use Cases

날짜	Date	Blueprint	작업 요약	Summary
04-03	`maxtrans_remaining_improvements`	Translator/History export 설계	Translator/History export design	2 / 10
04-04	`subway_ui_fixes_v2`	UI 개선 (검색·정렬·파싱)	UI improvements (search, sort, parsing)	1 / 10
04-04	`lm_studio_3tier_improve`	모델 자동 감지 + 타임아웃 설정	Model auto-detect + timeout config	1 / 10
04-07	`maxtrans_full_encryption`	AES-256-GCM 전체 암호화	AES-256-GCM full encryption	1 / 10
04-09	`harness-debug on autotrade-bot`	DT 파이프라인 버그 제거 (3라운드)	DT pipeline bug elimination (3 rounds)	3 / 10
04-15	`inspect on kis-client`	vendored 패키지 13카테고리 감사	Vendored package 13-category audit	0 / 10
04-16	`autodebug on autotrade-bot DT`	DT 중복 포지션 + sell 실패 자동 수정·배포·검증	DT duplicate position + sell failure auto-fix, deploy, verify	1 / 10

💡

모든 사례에서 cloud 스텝이 0~3회. /inspect는 read-only라 cloud 0회. /harness-debug도 3라운드에 cloud 3회로 수렴.

All cases show 0–3 cloud steps. /inspect is read-only (0 cloud). /harness-debug converged in 3 rounds = 3 cloud steps.