에이전트 프레임워크 스터디 Day 10: harness는 팀 아키텍처를 만드는 공장이다

Planner가 repo 상태를 모른다.
Reviewer가 실제 lint/test 결과를 모른다.
Coder가 ticket acceptance criteria를 잊는다.
QA가 어떤 브랜치/diff를 봐야 하는지 모른다.
각 agent가 서로 다른 사실을 기억한다.

Task Contract:
  intent
  scope
  acceptance criteria
  no-touch area
  source refs
  allowed tools
  output artifact
  verification required

Planner harness:
  contract -> plan / risk / sequence

Implementer harness:
  contract + plan -> changed files / local checks

Reviewer harness:
  contract + diff + checks -> pass/fail findings

Publisher harness:
  contract + final diff + gate result -> commit/push/report

Fixed:
  repo path
  content folder convention
  frontmatter shape
  format/lint/build commands
  commit scope
  public URL verification
  ticket report format

Variable:
  post topic
  examples
  article structure
  external references
  final wording

Fixed:
  git status/diff inspection
  untracked file review
  deterministic checks
  OCR or fallback reviewer
  high/medium finding resolution rule
  no remote handoff on unresolved blockers

Variable:
  project-specific commands
  severity judgement evidence
  whether OCR must rerun after fix

무엇은 매번 같아야 하는가?
무엇은 매번 판단해야 하는가?
무엇은 절대 자동화하면 안 되는가?

Harness Template
  + Task Contract
  + Profile / Context Scope
  + Tool Allowlist
  + Workflow Steps
  + Artifact Schema
  + Verification Gate
  + Feedback Rule
        |
        v
Runnable Work Unit

- 같은 Hermes 세션 안에서 수행되는 절차일 수도 있고
- 별도 profile/spoke로 실행될 수도 있고
- cron job일 수도 있고
- CI job일 수도 있고
- MCP tool 뒤쪽의 worker일 수도 있습니다.

Input:
  series = agent-framework
  next_day = 10
  topic = harness as team architecture factory

Allowed tools:
  file write
  pnpm format/lint/build
  git commit/push main

No-touch:
  unrelated local drafts
  provider/model config
  gateway restart

Artifacts:
  day10.mdx
  local verification log
  commit hash
  public URL
  ticket report

Done when:
  format/lint/build pass
  pushed HEAD == origin/main
  public route verified or deploy evidence recorded

Input:
  large source/log/session corpus
  question

Allowed tools:
  local index/search/router
  source coordinate extraction

No-touch:
  durable memory write
  remote upload of raw logs

Artifacts:
  selected source spans
  confidence notes
  stale/missing evidence flags

Done when:
  cloud reasoning receives coordinates, not raw dump

planner
coder
reviewer
manager

이 작업은 어떤 context를 오래 들고 있어야 하는가?
이 작업의 실패 비용은 어느 정도인가?
이 작업 결과가 hub에 흡수될 가치가 있는가?

Hub:
  user conversation
  final decision
  ticket/result ledger
  reusable rule absorption

Stable Spoke:
  repeated project context
  dense local conventions
  recurring verification pattern

Disposable Spoke:
  one-off exploration
  isolated risky context
  archive/discard after result

if repetition is low and context is small:
  stay in hub session

if repetition is high and project conventions are dense:
  use stable profile

if task is risky/noisy/exploratory:
  use disposable profile or isolated worktree

when to use
source-of-truth paths
commands
pitfalls
verification checklist
report format

skill document
+ active config
+ enabled tools
+ repo state
+ ticket state
+ session context
+ cron delivery mode
+ external credentials availability
+ local files/artifacts

- canonical checkout이 dirty인가?
- origin/main이 앞서 있는가?
- node_modules가 있는가?
- 이번 run은 commit/push standing approval 범위인가?
- unrelated draft가 같이 build에 섞이는가?

type AgentHarness = {
  name: string;
  trigger: TriggerContract;
  input: InputSchema;
  context: ContextPolicy;
  tools: ToolPolicy;
  permissions: PermissionPolicy;
  workflow: WorkflowStep[];
  artifacts: ArtifactContract[];
  verification: VerificationGate[];
  feedback: FeedbackRule[];
  disposition: DispositionPolicy;
};

trigger:
  언제 이 harness를 쓸지

input:
  무엇을 받아야 실행 가능한지

context:
  어떤 memory/session/file/source를 넣을지

 tools:
  어떤 도구를 노출하고 어떤 도구는 막을지

permissions:
  read-only / local write / external side effect / destructive action 경계

workflow:
  deterministic step과 agent judgement step의 순서

artifacts:
  중간/최종 산출물의 위치와 형식

verification:
  pass/fail 기준과 명령

feedback:
  memory, skill, trace, ticket 중 어디에 무엇을 남길지

disposition:
  결과를 hub에 absorb할지, archive할지, discard할지

새 agent = 새 persona

새 agent = 새 harness instance

Reviewer에게 리뷰를 맡겼다.
Reviewer가 길게 설명했다.
무엇이 block인지, 무엇이 suggestion인지 알 수 없다.

Reviewer output:
  passed: boolean
  blocking_issues: []
  verification_gaps: []
  non_blocking_suggestions: []

Worker가 파일을 읽다가 수정까지 했다.
수정하다가 commit/push까지 시도했다.

Tool policy:
  read_file/search allowed
  write_file requires local-write harness
  git push requires publish harness + final gate

이번 티켓 진행 상황을 memory에 저장했다.
다음 주에는 이미 stale한 사실이 system context에 들어간다.

facts/preferences -> memory
task progress -> ticket/session/cron output
procedure -> skill
workflow evidence -> trace

모델이 “검증했습니다”라고 말했다.
어떤 명령을 어디서 실행했는지 없다.

Verification artifact:
  command
  cwd
  exit code
  relevant output
  skipped reason if any

한 번 조사한 후보 기술의 긴 README 요약이 hub memory에 저장된다.
다음 briefing마다 같은 후보가 새 추천처럼 나온다.

watch/candidate state -> briefing_seen.json
absorbed rule -> skill/reference
stable user preference -> memory

1. 이 작업은 반복되는가?
2. 실패했을 때 복구할 수 있는가?
3. 산출물이 어디에 남는가?
4. 어떤 정보가 hub에 흡수되어야 하는가?
5. 어떤 정보는 버려야 하는가?
6. 검증은 deterministic한가, agent judgement인가?
7. 사람 개입은 위험도에 맞게 배치되어 있는가?
8. 다음 실행에서 재사용할 수 있는 trace가 남는가?

나쁜 방향:
  agent를 많이 만든다
  각 agent에게 긴 역할 프롬프트를 준다
  결과를 채팅으로만 받는다

좋은 방향:
  반복 작업을 harness로 정의한다
  입력/도구/권한/산출물/검증을 고정한다
  필요한 경우에만 profile/spoke를 쓴다
  결과를 ticket/artifact/trace/skill로 나누어 남긴다

name: seojing-study-publish
trigger:
  scheduled 04:00 run with standing approval

input:
  series
  next day number
  topic direction

context:
  origin/main worktree
  existing series posts
  seojing skill
  content conventions

tools:
  file write
  pnpm prettier/format/lint/build
  git commit/push
  ticket report

permissions:
  local write: allowed for intended MDX
  commit/push: allowed only for approved study lane
  unrelated files: no-touch
  gateway restart: forbidden

workflow:
  1. inspect repo state
  2. use isolated worktree if canonical tree is dirty/behind
  3. choose next Day N from origin/main
  4. write MDX
  5. run formatting and build checks
  6. commit only intended file
  7. push to origin main
  8. verify origin/main equality and public/deploy evidence
  9. record ticket report and workflow trace

artifacts:
  apps/web/content/study/agent-framework/dayN.mdx
  command outputs
  commit hash
  public URL
  ticket report

feedback:
  if repeated failure -> patch skill/reference
  if success -> workflow trace
  if new reusable rule -> skill update

- CLI command로 만들기
- cron job으로 만들기
- profile worker로 만들기
- MCP tool로 노출하기
- eval dataset으로 만들기

harness = AI를 둘러싼 실행 환경

harness = 반복 가능한 전문 작업 단위를 찍어내는 팀 아키텍처 공장

input contract
+ context policy
+ tool/permission boundary
+ workflow sequence
+ artifact contract
+ verification gate
+ feedback rule
+ disposition policy

이 프레임워크는 몇 개의 agent를 만들 수 있나?

이 프레임워크는 harness를 얼마나 명확하게 정의하고 실행하고 검증하고 학습시키는가?