에이전트 프레임워크 스터디 Day 5: 워크플로와 에이전트의 경계를 나누는 법

workflow: seojing-agent-framework-study-publish

1. repo 상태 확인
2. dirty canonical checkout이면 origin/main 기반 임시 worktree 생성
3. 기존 dayN.mdx 목록 확인
4. 다음 Day 번호 선택
5. 모델이 글 주제/본문 작성
6. prettier 적용
7. format:check / lint / build
8. 변경 파일 scope 확인
9. commit
10. push HEAD:main
11. fetch origin main
12. local HEAD == origin/main 확인
13. public URL과 검증 결과를 report에 기록
14. workflow trace 저장

- 2번에서 막힘: canonical checkout이 dirty인데 worktree 생성 실패
- 7번에서 막힘: MDX 문법 또는 lint 문제
- 10번에서 막힘: push 권한/remote 문제
- 12번에서 막힘: remote가 예상과 다름
- 14번에서 막힘: workflow trace 저장 도구 문제

- 후보 기술의 채택 가치 판단
- 사용자의 현재 수준에 맞는 설명 순서 선택
- 실패 로그가 이번 변경 때문인지 기존 문제인지 분류
- 여러 증거가 충돌할 때 어떤 상태로 보고할지 결정
- 다음 글을 쓸지, 오늘은 쓰지 않는 게 나은지 판단
- 반복된 작업에서 skill로 승격할 만한 규칙 추출

{
  "name": "example-agent-framework",
  "stars": 25000,
  "pushed_at": "2026-06-14T18:56:53Z",
  "description": "framework for building AI agents"
}

- 이 도구가 OkayJing의 현재 문제를 해결하는가?
- Hermes와 겹치는 런타임을 또 설치하는가?
- MCP/observability/workflow 같은 표준 방향을 강화하는가?
- 로컬-first, 개인정보, 되돌리기 가능성에 맞는가?
- 지금은 watch_only인가, 현재 적용할 practice가 있는가?

이 작업은 같은 입력이면 거의 같은 순서로 처리해도 되는가?

예: LMS assignment crawl
- 로그인 세션 확인
- 과제 페이지 접근
- assignment DB upsert
- schedule DB와 구분
- last_seen_at 비교
- stale/pending/completed 상태 판단
- briefing용 요약 생성

예: 새로운 OkayJing Local UI 방향 판단
- Discord를 얼마나 대체할 것인가?
- Office/Sessions/Code 중 어디를 우선할 것인가?
- 모바일에서 같은 IA를 유지할 것인가, 별도 탭을 만들 것인가?
- 어떤 참고 제품을 실제로 연구할 것인가?

잘못 실행했을 때 되돌리기 쉬운가?
외부에 영향을 주는가?
사용자 데이터나 비용, 공개 상태가 걸려 있는가?

낮은 위험
- 로컬 상태 파일에 dedupe 항목 추가
- 임시 worktree에 새 MDX 작성
- dry-run dashboard render
- read-only status check

중간 위험
- SEOJing main에 content commit/push
- cron prompt의 좁은 문구 수정
- skill procedure patch

높은 위험
- gateway restart
- provider/model 변경
- secret rotation
- public API 노출
- 데이터 삭제
- 비용이 큰 외부 서비스 설치

좋은 개입 지점
- 공개 push 직전: 변경 scope와 검증 결과 확인
- gateway restart 전: active work와 영향 범위 확인
- 비용/외부 계정 연결 전: 권한과 비용 확인
- destructive command 전: 대상과 rollback 확인

나쁜 개입 지점
- 이미 승인된 routine의 매 단계마다 확인
- read-only check 전 확인
- 실패 원인을 보지도 않고 “계속할까요?” 묻기
- 추천과 현재 적용을 구분하지 않고 매일 같은 승인 요청 반복

facts/preferences -> memory
procedures -> skills
work state -> ticket / work ledger
conversation -> session
repeated execution -> cron
human-facing display -> dashboard / Discord / Local UI
verification evidence -> report / trace / artifact

- 어제의 작업 진행 상태가 장기 기억으로 남아 stale해진다.
- skill로 내려가야 할 절차가 매번 prompt에 복붙된다.
- ticket에 있어야 할 blocker가 final response에만 남는다.
- dashboard는 예쁘지만 source of truth가 아니다.
- cron output과 report가 분리되어 08:00 briefing이 오래된 정보를 새 것처럼 말한다.

나쁜 검증
- 글이 괜찮아 보인다.
- 아마 build 될 것이다.
- URL도 곧 될 것이다.
- 리뷰어가 나중에 볼 것이다.

좋은 검증
- pnpm format:check exit 0
- pnpm lint exit 0
- pnpm build exit 0
- git diff --check exit 0
- git fetch 후 HEAD == origin/main
- public route probe 또는 deploy evidence 확인
- dashboard dry-run JSON 생성 성공

실행 -> 증거 -> 평가 -> 절차 수정

[scheduled]
  -> collect_state
  -> decide_scope
  -> draft_artifact
  -> verify_locally
  -> review_gate
  -> publish_or_record
  -> trace_and_report
  -> done | blocked

collect_state
- deterministic: repo, tickets, cron outputs, logs, existing files 읽기
- agent: 어떤 정보가 stale한지 판단

decide_scope
- deterministic: standing approval과 hard safety rules 확인
- agent: 오늘 publish할 주제가 충분한지 판단

draft_artifact
- deterministic: 파일 경로, frontmatter, slug 규칙
- agent: 본문 구성과 설명 깊이

verify_locally
- deterministic: format/lint/build/test
- agent: 실패 원인 분류와 수정 방향

review_gate
- deterministic: diff scope, secret scan, unsupported extension 여부
- agent: review finding의 blocker 여부 판단

publish_or_record
- deterministic: commit/push/report 경로
- agent: 공개하지 않을 때 이유 설명

trace_and_report
- deterministic: trace-add/analyze, ticket report
- agent: 아침에 볼 수 있게 요약

왜 워크플로인가?
- 반복되는 공개 publish 루틴이다.
- dirty tree contamination을 막아야 한다.
- 검증된 파일만 push해야 한다.

어디가 에이전트 판단인가?
- 다음 글의 주제와 설명 순서
- build 실패가 새 글 때문인지 기존 문제인지
- 오늘 okayJing self-reflection post까지 쓸 가치가 있는지

왜 워크플로인가?
- 매일 같은 시간에 같은 state sources를 읽어야 한다.
- dedupe state가 있어야 반복 추천을 막는다.
- stale context를 표시해야 한다.

어디가 에이전트 판단인가?
- 어떤 후보가 오늘 실제로 중요해졌는지
- 이미 적용된 practice를 “현재 적용”으로 분류할지
- 사용자가 아침에 봐야 할 focus를 무엇으로 좁힐지

먼저 필요한 것
- product direction
- device-specific UX
- API/gateway boundary
- verification criteria
- non-goals

그 다음 워크플로화할 것
- shell/nav 구현
- Sessions read-only API
- Code file tree API
- mobile overflow regression check
- PWA cache verification

1. 이 기능은 반복 업무인가, 열린 판단인가?
2. 반복 업무라면 상태 기계로 쪼갤 수 있는가?
3. 모델이 반드시 판단해야 하는 단계는 어디인가?
4. deterministic check로 증명할 수 있는 단계는 어디인가?
5. 실패하면 어디에 blocked 상태를 남길 것인가?
6. 결과물은 artifact인가, memory인가, ticket report인가?
7. 사람 승인은 위험이 바뀌는 지점에 있는가?
8. 이 기능이 실패했을 때 다음 실행이 배울 trace가 남는가?
9. 같은 절차가 3번 이상 반복되면 skill/script로 내려갈 수 있는가?
10. “에이전트가 알아서”라는 말 뒤에 숨은 책임이 없는가?

매일 GitHub에서 좋아 보이는 AI 도구를 찾아서 추천해줘.

workflow
1. watch module 목록을 읽는다.
2. GitHub API로 후보 repo metadata를 가져온다.
3. briefing_seen.json에서 dedupe_key를 찾는다.
4. 새 항목이면 추가한다.
5. 기존 항목이면 last_seen_at/evidence만 갱신한다.
6. JSON validation을 통과해야 저장한다.

agent judgement
- standard_alignment / okayjing_differentiator / watch_only / avoid_for_now 분류
- 현재 OkayJing 문제와 연결되는지 판단
- 설치가 아니라 practice 흡수로 충분한지 판단
- 08:00 briefing에 올릴 만큼 변화가 있는지 판단

Day 1: harness
  모델이 아니라 실행 환경 전체

Day 2: tool contract
  함수 호출이 아니라 책임/위험/검증 계약

Day 3: context/state
  프롬프트 더미가 아니라 실행 상태 조립

Day 4: observability
  채팅 기록이 아니라 개선 가능한 run 증거

Day 5: workflow vs agent boundary
  반복 가능한 골격과 열린 판단의 분리

- 한 에이전트가 다른 작업자에게 무엇을 넘기는가?
- handoff는 메시지인가, 계약인가, artifact인가?
- A2A나 MCP 같은 프로토콜은 어디에 들어오는가?
- profile/spoke/work-ledger는 어떤 단위로 분리되어야 하는가?

워크플로
- 반복 가능하다.
- 단계와 상태가 보인다.
- 실패 위치를 남긴다.
- deterministic check가 붙는다.

에이전트 판단
- 불확실한 선택을 분류한다.
- 증거가 충돌할 때 해석한다.
- 사용자의 목적과 현재 맥락에 맞춘다.
- 절차로 내려갈 수 있는 규칙을 추출한다.

사람 개입
- 위험이 바뀌는 지점에 둔다.
- 승인 피로를 만들지 않는다.
- 외부 영향, 비용, 삭제, credential, 공개 배포에서 강해진다.