에이전트 프레임워크 스터디 Day 1: 프레임워크보다 먼저 실행 환경을 설계하기

while not done:
  context = build_context(user_request, memory, files, state)
  decision = model(context, available_tools)

  if decision.type == "tool_call":
    result = run_tool(decision.tool, decision.args)
    state.append(result)
    continue

  if decision.type == "final":
    return decision.message

Harness = AI가 일을 수행할 수 있게 만드는 실행 환경

1. Model layer
   - 어떤 모델을 쓸지
   - fallback이 있는지
   - 빠른 모델과 깊은 모델을 어떻게 나눌지

2. Context layer
   - system prompt
   - skills
   - user preferences
   - project docs
   - retrieved memory
   - recent session state

3. Tool layer
   - terminal
   - file read/write/search
   - browser
   - GitHub
   - calendar/email
   - image/voice/document tools

4. Permission layer
   - read-only
   - reversible local write
   - external side effect
   - destructive/costly/credentialed action

5. Workflow layer
   - plan
   - implement
   - verify
   - review
   - report
   - retry or block

6. Validation layer
   - tests
   - lint/build
   - secret scan
   - OCR/reviewer gate
   - public URL probe
   - dashboard REST readback

7. State and artifact layer
   - tickets
   - cron output
   - memory
   - sessions
   - generated files
   - workflow traces

8. Feedback layer
   - failure logs
   - user corrections
   - skill patches
   - repeated workflow candidates

          ┌─────────────────────────────┐
          │        User / Schedule       │
          └──────────────┬──────────────┘
                         │
                         v
┌──────────────────────────────────────────────────┐
│                    Harness                       │
│                                                  │
│  context  ──>  model  ──>  tool runtime          │
│     │          │             │                   │
│     │          │             v                   │
│     │          │        permissions              │
│     │          │             │                   │
│     v          v             v                   │
│  memory     workflow     validation              │
│     │          │             │                   │
│     └──────────┴──────> artifacts/traces         │
└──────────────────────────────────────────────────┘
                         │
                         v
              final answer / ticket / post

일회성 coding harness:
- 현재 repo의 코드를 고친다.
- 테스트를 돌린다.
- diff를 보고한다.
- 세션이 끝나면 대부분의 맥락이 사라진다.

개인 운영 harness:
- 여러 날에 걸친 작업 상태를 이어간다.
- 사용자의 선호와 금지 사항을 기억한다.
- 반복 업무를 cron으로 실행한다.
- Discord, ticket, blog, dashboard에 결과를 남긴다.
- 실패 원인을 다음 실행에 반영한다.

- 오늘이 몇 번째 글인지 기존 파일에서 확인한다.
- backend series와 agent-framework series의 경계를 지킨다.
- unrelated draft를 실수로 stage하지 않는다.
- format/lint/build를 실제로 통과한다.
- Notjing/OCR이 MDX를 못 보면 대체 리뷰 근거를 남긴다.
- commit type이 repo 규칙에 맞는지 확인한다.
- push 후 origin/main과 local HEAD가 같은지 확인한다.
- 8AM briefing이 public URL을 보고할 수 있게 남긴다.
- 반복 성공 trace를 workflow compilation 후보로 기록한다.

Tool Contract
- name: 도구 이름
- purpose: 어떤 일을 위한 도구인가
- input schema: 어떤 인자를 받는가
- output schema: 성공/실패를 어떻게 표현하는가
- side effects: 파일, 네트워크, 외부 서비스 변경이 있는가
- risk tier: read-only / local write / external / destructive
- preconditions: 실행 전에 무엇이 필요한가
- verification: 실행 후 무엇으로 성공을 확인하는가

read-only:
  git status
  date
  pnpm --version

local write:
  pnpm format
  git add
  file generation

external side effect:
  git push
  gh pr create
  cloud deploy

credential/destructive:
  secret rotation
  rm -rf
  database migration

facts/preferences -> memory
procedures -> skills
work state -> tickets / workflow DB
conversations -> sessions
repeat execution -> cron
human-facing display -> dashboard / Discord
verification evidence -> reports / artifacts / traces
secrets -> .env only
settings -> config.yaml

workflow에 가까운 것:
- 매일 04:00 self-improvement 실행
- 매일 08:00 briefing 작성
- LMS 과제/일정 수집
- SEOJing study post 발행 절차
- dashboard 상태 렌더링
- Notjing final gate

agent에 가까운 것:
- 새로운 기술 후보 조사와 판단
- 글의 주제 선택과 구성
- 복잡한 버그 원인 가설 세우기
- 사용자의 모호한 요청을 요구사항으로 좁히기

반복 가능하고 검증 가능한 뼈대는 workflow로 둔다.
판단이 필요한 지점만 agent에게 맡긴다.

- 판단이 틀렸나?
- 도구 실행이 실패했나?
- 검증이 부족했나?
- 권한 경계가 잘못됐나?
- 상태 기록이 stale했나?

극단 A: 모든 것을 물어본다.
- 사용자는 계속 승인 버튼을 눌러야 한다.
- 에이전트가 일을 끝까지 못 한다.
- 승인 피로가 생긴다.

극단 B: 아무것도 묻지 않는다.
- 외부 side effect가 조용히 일어난다.
- 잘못된 삭제/배포/비용 발생 위험이 커진다.
- 사용자가 통제감을 잃는다.

Level 0: read-only discovery
  -> 자동 진행

Level 1: reversible local write
  -> 명확한 요청/standing approval이 있으면 자동 진행

Level 2: external side effect
  -> 명확한 요청/standing approval이 필요

Level 3: destructive, credentialed, costly, privacy-sensitive
  -> 원칙적으로 명시 확인 필요

- 어떤 요청/cron/ticket에서 시작했는가
- 어떤 skill과 context가 로드되었는가
- 어떤 도구를 어떤 순서로 실행했는가
- 어떤 출력이 검증 근거가 되었는가
- 어떤 검증이 실패했는가
- 어떤 판단으로 block/skip/done 처리했는가
- 다음 실행에서 재사용할 절차가 있는가

ticket -> session -> tool output -> artifact -> verification -> report -> workflow trace

1. Primitive clarity
   agent, tool, session, memory, state, artifact, trace가 구분되는가?

2. Workflow vs agent separation
   반복 가능한 절차와 열린 판단을 나눌 수 있는가?

3. Durable state
   긴 작업이 중단되어도 이어갈 수 있는가?

4. Tool contract
   도구 schema, side effect, 권한, 검증 조건이 명확한가?

5. Context assembly
   skill, memory, project docs, retrieved facts를 어떻게 조립하는가?

6. Human control
   위험도에 따라 승인/중단 지점을 설계할 수 있는가?

7. Observability
   tool call, decision, artifact, verification trace가 남는가?

8. Evaluation
   반복 workflow를 회귀 테스트하거나 비교할 수 있는가?

9. Interoperability
   MCP/A2A 같은 표준 경계와 연결될 수 있는가?

10. Local-first fit
   개인 데이터, 한국어 작업 맥락, Mac mini 운영에 맞는가?

에이전트가 파일을 고쳤다.
테스트는 돌리지 않았다.
최종 응답은 "수정했습니다"라고 말한다.

수정 -> format -> lint/test/build -> diff 확인 -> 보고

"PR #12가 대기 중"을 장기 memory에 저장한다.
며칠 뒤 PR은 merge됐지만 memory는 남아 있다.
다음 작업에서 오래된 상태를 현재 사실처럼 사용한다.

매일 SEOJing 글을 발행하는데,
어떤 날은 format만 하고,
어떤 날은 build를 빼먹고,
어떤 날은 push 후 origin/main 확인을 안 한다.

매일 아침 같은 GitHub 라이브러리를 "새 후보"처럼 추천한다.

내 에이전트가 안전하게 일하고,
중단되어도 이어지고,
검증된 결과만 보고하고,
실패에서 배울 수 있게 만드는 실행 환경은 무엇인가?

Day 1: harness와 실행 환경
Day 2: MCP와 tool contract
Day 3: skill/procedural memory
Day 4: context assembly와 state/memory 분리
Day 5: workflow orchestration과 checkpoint
Day 6: human-in-the-loop와 권한 경계
Day 7: observability/tracing/evaluation
Day 8 이후: Hermes/OpenClaw류 프레임워크의 내부 확장 지점