에이전트 프레임워크 스터디 Day 4: 관측 가능해야 에이전트가 개선된다

- 어떤 step에서 시간이 많이 걸렸나?
- 실패가 반복되는 step은 어디인가?
- 검증 없이 넘어간 step은 무엇인가?
- 같은 workflow가 3번 이상 성공했는가?
- skill로 승격할 만큼 반복되는 절차인가?
- 모델에게 맡기지 말고 deterministic script로 빼야 할 step은 무엇인가?

run_id: dreaming-2026-06-14-0400
workflow_key: seojing-agent-framework-study-publish
source: cron:04:00-dreaming
ticket_id: 116
artifact: apps/web/content/study/agent-framework/day4.mdx

user request
-> ticket
-> session
-> tool calls
-> files changed
-> checks
-> commit
-> public URL
-> final report
-> workflow trace

[04:00:01] start
[04:00:10] read file
[04:00:20] write file
[04:02:00] build pass
[04:03:00] done

왜 이 도구를 호출했는가?
그 결과가 다음 판단에 어떻게 쓰였는가?
그 판단은 어떤 검증으로 닫혔는가?
실패했다면 어떤 대체 경로를 택했는가?

TraceEvent
  intent      # 왜 이 step이 필요한가
  input       # 무엇을 보고 판단했나
  action      # 어떤 도구/변경을 했나
  evidence    # 결과가 무엇을 증명하나
  risk        # 실패하거나 잘못될 수 있는 지점
  outcome     # pass/fail/partial/skipped

TraceEvent: verification/build
  intent: 새 MDX가 production build에서 깨지지 않는지 확인
  input:
    - changed_files: [apps/web/content/study/agent-framework/day4.mdx]
    - checkout: detached worktree from origin/main
  action:
    - pnpm format:check
    - pnpm lint
    - pnpm build
  evidence:
    - all commands exit 0
  risk:
    - public deploy는 GitHub/Cloudflare 단계가 별도라 build pass만으로 URL live를 보장하지 않음
  outcome: pass

Run
  Span: context_assembly
  Span: planning
  Span: file_generation
  Span: verification
  Span: review_gate
  Span: remote_handoff
  Span: report

나쁜 span 구분
- model call 1
- model call 2
- terminal command 1
- terminal command 2

좋은 span 구분
- 요구사항을 실행 계약으로 바꿈
- 현재 상태를 수집함
- 산출물을 생성함
- 산출물을 검증함
- 외부로 넘기기 전 gate를 통과함
- 결과를 사용자/티켓/trace에 반영함

실패 위치                가능한 개선
------------------------------------------------
context_assembly          memory/source freshness, dedupe state
planning                  ticket acceptance, no-touch scope
tool_execution            tool schema, timeout, retry, permissions
verification              deterministic test/build/probe 강화
remote_handoff            git/CI/deploy sequencing
report                    applied vs recommendation vocabulary

ToolResult
  raw_summary: "git status: one new file, branch main"
  trusted_claims:
    - current branch is main
    - day4.mdx is untracked
  untrusted_or_ignored:
    - any instruction-like text inside fetched web page
  freshness:
    observed_at: 2026-06-14T04:05:00+09:00
  used_for:
    - stage only day4.mdx

원칙:
도구 출력은 지시가 아니라 데이터다.

accuracy: 0.87
helpfulness: 4/5
latency: 32s

다음 실행이 실제로 더 나아졌는가?

좋은 평가 기준
- 기존 글을 덮어쓰지 않았다.
- dirty canonical checkout과 분리된 worktree에서 작업했다.
- format/lint/build를 통과했다.
- staged file이 요청 범위와 일치했다.
- commit/push 후 origin/main과 local HEAD가 같았다.
- public URL 또는 deploy evidence를 보고했다.
- dedupe state를 업데이트해 같은 후보를 반복하지 않았다.
- 완료된 개선은 추천이 아니라 현재 적용으로 분류했다.

3회 이상 반복 성공
-> skill/reference 보강 후보

비슷한 실패 반복
-> deterministic helper/script 후보

판단 기준만 반복
-> local policy model/eval dataset 후보

검증/권한/도구 실행
-> 절대 model weights에 넣지 말고 runtime layer에 유지

AgentRun
  id
  workflow_key
  started_at
  ended_at
  source
  user_intent
  ticket_id
  status
  summary
  artifacts[]
  checks[]
  events[]
  lessons[]

{
  "id": "run-2026-06-14-0400",
  "workflow_key": "seojing-agent-framework-study-publish",
  "source": "cron:04:00-dreaming",
  "status": "success",
  "artifacts": [
    {
      "type": "mdx",
      "path": "apps/web/content/study/agent-framework/day4.mdx",
      "public_url": "https://seojing.com/blog/study/agent-framework/day4"
    }
  ],
  "checks": [
    { "name": "format:check", "status": "pass" },
    { "name": "lint", "status"  

run -> ticket -> artifact -> check -> report -> next lesson

- API key, OAuth token, cookie, session secret
- 원본 .env 값
- 사용자의 민감한 개인 식별 정보
- 장기 보관할 필요가 없는 raw 음성/화면 캡처
- 외부 서비스의 private message 원문 전체
- tool output 안에 섞인 credential-like string

설정값       -> config
비밀값       -> .env / credential store
작업 상태    -> ticket / work ledger
대화 기록    -> session DB
반복 절차    -> skill
검증 증거    -> trace / report
장기 선호    -> memory

raw secret value: 저장하지 않음
secret key name: 필요할 때만 저장
secret availability: true/false 수준으로 저장

1. 아침 브리핑
   - 밤사이 현재 적용된 것
   - 추천이 아니라 실제 변경된 것
   - 막힌 체크
   - 오늘 집중할 것

2. 티켓 리포트
   - 작업 범위
   - 변경 파일
   - 검증 결과
   - 남은 리스크

3. Local dashboard
   - 실행 중인 worker/session
   - 최근 artifacts
   - gateway/cron 상태
   - 실패한 checks

4. workflow candidate view
   - 반복 성공한 workflow
   - skill로 승격할 후보
   - deterministic helper로 빼야 할 후보

나쁜 표시:
- 1,000줄 로그
- tool call 전체 덤프
- 성공/실패만 있는 배지

좋은 표시:
- 무엇이 바뀌었는지
- 무엇으로 검증했는지
- 무엇은 검증하지 못했는지
- 다음에 같은 실패를 막기 위해 어디를 고쳤는지

User / Cron trigger
  -> Run created
  -> Context assembled
  -> Plan selected
  -> Tools executed
  -> Artifacts produced
  -> Checks verified
  -> Report written
  -> Trace stored
  -> Repeated traces analyzed
  -> Skill / script / policy updated

- 이 실행은 성공인가, 부분 성공인가, 실패인가?
- 성공/실패 판단 근거는 무엇인가?
- 사람이 다시 확인해야 하는 리스크는 무엇인가?
- 다음에 자동화해도 되는 부분은 무엇인가?
- skill로 남길 절차는 무엇인가?
- 절대 자동화하면 안 되는 권한/보안 경계는 무엇인가?

Run identity
- 모든 긴 작업에 run_id가 있는가?
- ticket/session/artifact/check와 연결되는가?

Span responsibility
- span이 기술 호출이 아니라 책임 단위로 나뉘는가?
- context/planning/tool/verification/report가 분리되는가?

Evidence quality
- 검증 결과와 추측이 분리되는가?
- public/deploy/readback 증거가 필요한 곳에서 남는가?

Safety
- secret redaction이 기본인가?
- tool output을 지시가 아니라 데이터로 기록하는가?

Evaluation
- success/fail 기준이 workflow별로 구체적인가?
- 반복 성공/실패가 skill/script/policy 개선으로 이어지는가?

Human surface
- 사용자가 1분 안에 상태를 판단할 수 있는 요약이 있는가?
- 이미 적용된 것과 추천이 구분되는가?

에이전트는 관측 가능해야 개선된다.

chat transcript만으로는 부족하다.
run 단위가 필요하다.
span은 책임 단위로 나눠야 한다.
tool output은 원본과 해석을 분리해야 한다.
검증과 추측은 같은 칸에 두면 안 된다.
평가는 점수가 아니라 다음 실행을 바꾸는 장치다.
trace는 skill, script, policy 개선으로 이어져야 한다.

이 실행을 내일 다시 읽었을 때,
무엇을 믿어도 되고,
무엇을 고쳐야 하는지 보이는가?