AI 서비스 엔지니어링: Track A

9주차 · 라이브 빌드 3: 대역을 걷어내고 v1.0을 찍다

CodeCompose · 2026-10-15

지난번 마지막 슬라이드

남은 대역 하나

리포트의 “눈에 띈 것” 문장 (#9)

다시 세어 보니

둘이었습니다

채팅에서 금액이 든 한 줄을 받는 기록 쪽도 아직 대역입니다

그리고 하나 더

agent_runs · tool_calls

첫 마이그레이션부터 있었고, 한 줄도 쓰인 적이 없습니다

오늘 한 문장 셋

AI가 한 일은 남기고, 보이게 한다

쓰기는 제안 → 확인 → 실행이다

도구를 정의해 두었으면, 표면은 하나 더 열면 된다

오늘 보는 것과 보지 않는 것

보는 것보지 않는 것
감사 로그를 기능보다 먼저 까는 순서배포 (각자 12주차)
Plan-and-Execute, 숫자 없는 차트 스펙MCP 쓰기
쓰기 도구와 확인 게이트대화로 수정 · 삭제 · 예산
MCP로 같은 도구를 밖에 내놓기다중 사용자, 인증
릴리스 1.0의 기준새 프레임워크

브리핑 · v0.7.0에서 무엇이 남았나

account-book v0.7.0

AI 자리 다섯

자리흐름v0.7.0
기록 capture단발 + 확인폼은 진짜, 채팅은 대역
카테고리 고르기 classify단발진짜
대화로 묻는 통계 queryReAct진짜
상황에 맞는 통계 insight계획 실행대역
문서 Q&A단발진짜

대역이 서는 이유는 두 가지

이유오늘
키가 없을 때남긴다. AI를 끄면 가계부는 그대로 돌아야 한다
진짜가 아직 없을 때지운다

ui_docs/stand-ins.md의 표를 다시 열면 둘째 이유가 몇 줄인지 보입니다

비어 있는 테이블 둘

테이블한 줄이 뜻하는 것
agent_runs에이전트 실행 한 번
tool_calls그 실행 안의 도구 호출 하나
  • 거래에는 source=agent와 run_id가 붙습니다
  • 그 run_id가 가리킬 행이 없습니다
  • “이 거래는 왜 여기 있지?”에 지금은 답할 수 없습니다

오늘의 순서

flowchart LR
    V7["v0.7.0"] --> A["0 · 감사 로그 기록"]
    A --> I["1 · 상황 통계 #9"]
    I --> C["2 · 채팅 기록"]
    C --> M["3 · MCP 읽기 전용"]
    M --> P["4 · 감사 로그 화면"]
    P -->|"v1.0.0"| E(["끝"])

중간 태그 없이, 다섯 부를 develop에 모아 v1.0.0 하나

브랜치와 모델

부브랜치모델
0audit-log없음
1api-outliers → insights-plan → insights-llm마지막 회전
2capture-plan → capture-gate → capture-chat마지막 회전
3mcp-read없음 (밖의 모델)
4audit-page없음

감사 로그를 왜 둘로 나눴나

  • 기록은 맨 앞에
    • 1 · 2 · 3부가 처음부터 남깁니다. 나중에 붙이면 같은 일을 세 번 고칩니다
    • 2부의 확인 대기 상태는 아예 이 테이블에 삽니다
  • 화면은 맨 뒤에
    • 네 자리와 MCP 호출이 다 쌓인 뒤라야 볼 것이 있습니다

출발점에 서기

git switch -c try-v0.7.0 v0.7.0
make dev && make docs
어디지금
채팅: “어제 점심 김밥천국 8500원 카드로”대역이 정규식으로 읽는다
/reports의 “눈에 띈 것”규칙 문구
SELECT count(*) FROM agent_runs;0

오늘 끝에 이 셋이 모두 바뀝니다

0부 · 감사 로그 기록

feature/audit-log · 모델 없음

운영 로그와 감사 로그는 다르다

운영 로그감사 로그
남기는 것식별자, 도구명, 시간, 토큰, 결과 코드발화 원문, 인자, 금액, 가맹점
누가 보나운영자. 수집기로 흘러간다사용자 본인. DB 안
답하는 질문”느려졌나, 깨졌나""이 거래는 왜 여기 있지”

운영 로그에 금액이 한 번 섞이면, 그 로그가 흘러간 모든 곳을 지워야 합니다

무엇을 정하나

정할 것오늘의 답
누가 쓰나agent가 api를 부른다. agent는 DB를 모른다
언제 쓰나읽기 자리는 끝날 때 한 번. 쓰기 자리는 제안 · 확인 때
칸이 모자라다자리 · 흐름 · 끊긴 이유를 더하는 마이그레이션
기록이 실패하면?

기록이 실패하면

읽기 자리는 답을 막지 않는다

쓰기 자리는 제안을 내지 않는다

확인할 근거가 없는 카드는 띄우지 않습니다

0부 지시 프롬프트

감사 로그를 기록하자. 화면은 아직 만들지 마. Refs #<감사 로그 이슈>

- 읽을 것: docs/ai/README.md 원칙 7, agent-loop.md 9장, development-rules 6.4
- api: agent_runs에 seat, flow, stop_reason 칸을 더하는 마이그레이션.
  실행 하나와 그 도구 호출들을 받는 엔드포인트. api-contract에 같이 적어라
- agent: RunRecorder 포트와 api 어댑터.
  지금 있는 네 자리(/capture, /classify, /chat, /ask)가 끝날 때 남기게 하라
- 기록이 실패해도 답은 나간다. 실패는 운영 로그에 run_id와 코드만
- 운영 로그에 발화·금액·가맹점이 새지 않는지 보는 테스트를 넣어라

0부 확인할 것

어디무엇을
채팅에서 질문 하나agent_runs 한 줄, tool_calls 부른 만큼
api를 내리고 질문답은 나온다. 운영 로그에 실패 한 줄
docker compose logs agent발화도 금액도 없다
폼의 “AI로 고르기”seat=classify

1부 · 상황에 맞는 통계 #9

세 회전 · 모델은 마지막에

다음에 무엇을 부를지가

이전 결과에 달려 있나?

아니오 → Plan-and-Execute · 예 → ReAct · 하나 → 단발

#8과 #9는 흐름이 다릅니다

#8 대화 통계#9 상황 통계
흐름ReActPlan-and-Execute
왜”0건인데?”를 보고 다음 수를 바꾼다집계들이 서로 독립이다
LLM 호출질문마다 다르다두 번 (계획 · 조립)
병렬안 된다된다

훑고, 계획하고, 조립한다

graph TB
  A[리포트 진입] --> B["고정 호출 2회 (코드)"]
  B --> C{"LLM ① 무엇을 더 볼까"}
  C --> D["추가 집계 · 동시에"]
  D --> E{"LLM ② 차트 스펙 + 문장"}
  E --> F[검증]
  F -->|통과| G[SVG + 문장]
  F -->|실패| H[고정 리포트만]

처음 두 호출은 코드가 정합니다

데이터를 모르고 계획하면

“일단 다 불러 보자”가 가장 합리적인 답이 됩니다

그림은 선언으로, 숫자는 참조로

{
  "charts": [
    { "kind": "hbar", "source": "call_1",
      "x_field": "category_name", "y_field": "amount", "unit": "KRW" }
  ],
  "highlights": [
    { "text": "식비가 지난달보다 62,000원 늘었습니다.", "source": "call_2" }
  ]
}
  • 스펙에 데이터 배열이 없습니다. 값은 코드가 참조를 따라가 채웁니다
  • kind에 pie가 없습니다. 규칙을 적지 않고 표현할 수 없게 만듭니다

문장은 읽으면 이상한 걸 알아챕니다

막대 길이는 아무도 검산하지 않습니다

버리는 단위는 차트 하나, 문장 하나

검사걸리면
kind가 허용 목록에 있나그 차트만
source가 실제로 부른 id인가그 차트만
스펙에 값 배열이 있나그 차트만
문장의 숫자가 도구 결과에 있나그 문장만
훈계 금지어 (“아껴 쓰세요”)그 문장만
남은 것이 0개AI 영역을 그리지 않는다

1회전 · 이상치는 api가

#9의 첫 feature다. api에 이상치 집계를 더하자. 모델은 없다. Refs #9

- GET /v1/stats/outliers: 카테고리별 최근 여섯 달의 중앙값과 산포 기준으로
  평소 범위를 벗어난 거래. 판정 기준은 api가 정한다. 인자로 받지 마라
- 집계는 SQL로. 걸름 규칙은 /v1/summary와 같게
- 여섯 달이 안 되는 카테고리는 판정하지 않는다 (이유를 응답에)
- api-contract 6장에 옮기고 docs/ai/README.md 7.2에서 지워라

임계값을 모델이 말하면 같은 데이터가 달마다 다르게 특이해집니다

2회전 · 계획과 조립은 모델 없이

#9의 두 번째 feature다. agent에 POST /insights를 세우자.
모델은 가짜만 쓴다. Refs #9

- Mode.INSIGHT와 도구 세트(집계 다섯, 쓰기 없음)
- 고정 호출 둘 → 계획(LLM 1) → 추가 호출 동시 실행 → 조립(LLM 2) → 검증
- 차트 스펙 스키마와 검증표 그대로. 버리는 단위는 차트 하나, 문장 하나
- 숫자 검증은 #8의 number_check를 다시 쓴다. 새로 만들지 마라
- 감사 로그에 seat=insight, flow=plan_execute
- 테스트는 테이프(정해진 LLM 응답 + 정해진 도구 응답)로

3회전 · 모델이 고르고, 화면은 기다리지 않는다

#9의 마지막 feature다. 진짜 모델을 붙이고 리포트 화면을 바꾸자. Refs #9

- litellm으로 계획·조립 두 호출. temperature=0
- 캐시 키는 period · data_version · prompt_version · model. TTL은 쓰지 않는다
- ui: 고정 영역을 먼저 보내고 AI 영역만 HTMX로 뒤에 채운다
- 평가 세트 셋: 평범한 달, 큰 한 건이 있는 달, 새 카테고리가 생긴 달
- 대역 표와 AI 지도의 insight 자리를 고쳐라

캐시는 시간이 아니라 버전으로

period · data_version · prompt_version · model
  • TTL은 두 가지를 동시에 틀립니다
    • 아무것도 안 바뀌었는데 다시 부른다
    • 방금 거래를 고쳤는데 옛 리포트를 준다
  • prompt_version이 키에 없으면 프롬프트를 고친 뒤 평가를 믿을 수 없습니다

1부 확인할 것

어디무엇을
리포트 첫 화면AI를 기다리지 않고 뜬다
같은 달 두 번두 번째는 모델을 안 부른다 (감사 로그로 확인)
거래 하나 고치고 다시캐시가 깨진다
AGENT_BASE_URL 비우기대역 문구가 선다
make eval-insights평범한 달에 조용한가

모델은 시킨 일을 하려고 합니다

아무 일도 없는 달에도 무언가를 찾아냅니다

틀리진 않지만 쓸모없는 문장이 매달 쌓이면, 사용자는 그 영역을 안 읽습니다

2부 · 채팅으로 기록하기

계획 하나와 두 회전 · 처음 다루는 쓰기

지금까지 붙인 AI는 전부 읽기였습니다

틀려도 화면에 틀린 글이 뜰 뿐, DB는 그대로였습니다

이번 자리는 돈 기록을 씁니다

쓰기 한 번은 두 박자

sequenceDiagram
    participant U as ui
    participant AG as agent
    participant API as api
    U->>AG: POST /chat "김밥천국 8500원"
    AG->>AG: 읽기 → 분류
    AG->>API: 제안 저장 (awaiting_confirmation)
    AG-->>U: SSE proposal → 확인 카드
    Note over U,API: 아직 거래는 없다
    U->>AG: 확인 (proposal_id)
    AG->>API: POST /v1/transactions · 같은 멱등 키 · X-Confirmed-By
    AG-->>U: SSE message + 예산 페이스 한 줄

확인은 루프가 멈추는 자리

  • 확인 전에는 api로 거래가 가지 않습니다
  • awaiting_confirmation에서는 LLM을 부르지 않습니다
  • ui는 확인된 쓰기를 api로 직접 보내지 않습니다. 맥락은 agent가 들고 있습니다
  • 취소도 알립니다. 조용히 카드만 지우면 실행은 영원히 기다립니다

이 자리는 ReAct가 아닙니다

단발 + 확인 게이트

읽고, 분류하고, 제안하는 순서는 코드가 정합니다

0회전 · 계획: 정할 것

정할 것기울기
쓰기 도구 범위create_transaction 하나. 대역이 하던 만큼
제안을 어디에감사 테이블. agent가 재시작해도 끝까지 간다
확인 엔드포인트ChatAgent.decide() 자리가 이미 있다
수명24시간. 멱등 키 보존 기간과 같게
만료된 제안다시 제안한다
대역이 하던 것기록 직후 예산 페이스 한 줄도

대역이 하던 것을

진짜가 다 하는가

예산 페이스 줄이 사라지면, 사용자에게는 기능이 줄어든 것입니다

0회전 지시 프롬프트

채팅으로 기록하기의 계획을 쓰자. 제품 코드는 만들지 마. Refs #<채팅 기록 이슈>

- 읽을 것: tools.md 4.2·6·7장, agent-loop.md 3·6·9장, chat.md 5장,
  api-contract.md 3·4장, 그리고 지금 대역(ScriptedChatAgent)이 기록에서 하는 일 전부
- 정할 것마다 후보와 추천을 이유와 함께
- 대역이 하는 일과 진짜가 할 일을 줄 단위로 맞대 보는 표
- 확인·취소·만료·두 번 누름·agent 재시작을 sequence로
- 평가 세트: 대역이 알아듣던 문장, 못 알아듣던 문장, 넣지 말아야 할 문장
- 설계 문서와 어긋나는 곳은 고치지 말고 먼저 말해라

1회전 · 확인 게이트는 모델 없이

채팅 기록의 첫 feature다. agent에 기록 자리와 확인 게이트를 세우자.
모델은 가짜만 쓴다.

- Mode.CAPTURE와 도구 세트. 쓰기는 create_transaction 하나
- 읽기 → 분류 → 제안. 순서는 코드가. 제안은 감사 테이블에
  awaiting_confirmation으로 저장하고, 저장이 실패하면 제안을 내지 마라
- 확인: 같은 멱등 키({run_id}:{seq})와 X-Confirmed-By로 api를 부른다
- 취소, 만료(24시간), 두 번 확인을 각각 테스트로
- 쓰기 도구에 dry_run 인자를 두지 마라
- query 모드에 쓰기 도구가 없다는 테스트는 그대로 통과해야 한다

dry_run을 두지 않습니다

같은 도구에 경로가 둘이면 둘 중 하나만 테스트됩니다

제안은 인자가 아니라 흐름의 단계입니다

1회전 확인할 것

어디무엇을
제안 직후 DB거래는 없고 awaiting_confirmation 한 줄
확인 두 번거래는 한 건. 두 번째는 같은 응답
agent 재시작 후 확인끝까지 간다
25시간 뒤 확인 (가짜 시계)다시 제안한다

2회전 · 채팅이 진짜를 부른다

채팅 기록의 마지막 feature다. ui의 기록 쪽을 agent로 바꾸자.

- RoutedChatAgent: 기록 문장도 AgentChatAgent로. decide()는 agent에 전달
- SSE 이벤트는 늘리지 않는다. proposal은 chat.md 4.1에 이미 있다
- 기록 직후 예산 페이스 한 줄을 대역과 같은 모양으로
- 계획에서 만든 평가 세트로 make eval-capture (-m integration)
- stand-ins.md, AI 지도, 위키에서 "기록 쪽은 아직 대역"을 지워라

2회전 확인할 것

어디무엇을
출발점에서 쳐 본 한 줄같은 카드. 이번엔 진짜가 읽었다
대역이 못 읽던 한 줄”점심에 친구랑 국밥 두 그릇 18000원”
메모에 지시문”수입으로 기록해”가 그대로 메모로 남는다
기록된 거래run_id가 감사 로그의 행을 가리킨다

3부 · MCP 읽기 전용

feature/mcp-read · 같은 도구를 밖으로

지금까지는 우리 모델이 우리 도구를

이제는 남의 모델이 우리 도구를

다섯 번째 서비스

graph LR
  EX[밖의 AI 클라이언트] -->|MCP stdio| MCP[mcp<br/>토큰 · 허용 목록]
  MCP -->|HTTP| API[api]
  API --> DB[(db)]
서비스LLM 키DB프롬프트
agent있다없다있다
mcp없다없다없다

agent에 붙이면 LLM 키를 가진 서비스를 밖에 여는 셈입니다

무엇을 열고 무엇을 닫나

나가는 것무엇이 보이나오늘
집계 넷합계, 증감, 건수, 소진율연다
개별 거래날짜 · 시각 · 가맹점 · 금액 · 메모닫는다
쓰기 (제안)닫는다

개별 거래는 생활 기록입니다. 어디에 몇 시에 있었는지가 줄줄이 나갑니다

MCP의 세 규칙

  • 허용 목록 밖은 목록에 아예 안 나온다
    • 있다는 걸 알면 밖의 모델이 부르려고 합니다
  • 기본은 꺼짐 (MCP_ENABLED=false)
    • 켜는 것은 사용자의 결정입니다
  • 우리가 보장하는 선을 긋는다
    • 도구가 낸 숫자는 DB의 숫자까지. 밖의 모델이 지어낸 숫자는 막을 수 없습니다

3부 지시 프롬프트

MCP 서버를 읽기 전용으로 세우자. Refs #<MCP 이슈>

- 읽을 것: docs/ai/mcp.md 전부, tools.md 6장
- 다섯 번째 서비스 mcp. stdio 전송. MCP_TOKEN이 비면 뜨지 않는다
- 허용 목록 기본값은 집계 넷. 목록 밖은 목록 응답에도 없다
- 기간 이름을 푸는 코드와 도구 스키마가 agent에 있다. agent를 import하지 마라.
  둘이 같이 써야 하는 것을 어떻게 나눌지 먼저 제안하고 멈춰라
- 호출마다 감사 로그에 seat=mcp로. 클라이언트 이름도
- 분당 호출 상한. 도구 오류는 결과의 오류 플래그로

”먼저 제안하고 멈춰라”

서비스끼리 import하면 경계가 무너집니다

어떻게 나눌지는 사람이 정합니다

3부 확인할 것

Claude Code에 붙여서 묻습니다

어디무엇을
”이번 달 식비 얼마 썼어?”우리 DB의 숫자
”어제 김밥천국에서 뭐 샀어?”개별 거래 도구가 없어서 못 한다
도구 목록넷만 보인다
감사 로그seat=mcp 줄
MCP_TOKEN 비우기뜨지 않는다

4부 · 감사 로그 화면

feature/audit-page · 모아 본다

화면 문서부터 (ui_docs/pages/runs.md)

칸내용
목적”이 거래는 왜 여기 있지”에 답한다
목록언제 · 자리 · 상태 · 스텝 · 비용. 자리와 상태로 거른다
펼치기도구 · 인자 요약 · 결과 요약 · 확인 시각
들어오는 길AI 지도, 위키, source=agent 거래에서
하지 않는 것지우기, 고치기, 다시 실행. 읽기 전용

4부 지시 프롬프트

감사 로그를 보는 화면을 만들자. Refs #<감사 로그 이슈>

- 먼저 ui_docs/pages/runs.md를 화면 문서 틀대로 쓰고 커밋
- api: 실행 목록(자리·상태로 거름, 최신순, 페이지)과 실행 하나(도구 호출 포함)
- ui: /runs 목록, 행을 누르면 HTMX로 도구 호출을 펼친다
- 거래 상세에서 source=agent면 그 실행으로 가는 링크
- 인자와 결과는 요약으로. 원본 JSON은 펼침 안의 펼침에
- 쓰기 버튼은 하나도 없다

오늘 한 일 전부가 이 화면에

자리보이는 것
classifyAI로 고르기
query채팅 질문과 부른 도구들
insight계획 · 추가 호출 · 조립. 같은 달 두 번째는 없다
capture제안 → 확인 시각. 취소한 것도
mcp밖에서 부른 집계

릴리스 v1.0.0

라이브 빌드를 닫는다

1.0의 기준

기준확인
대역은 키가 없을 때만stand-ins.md의 “아직 없다”가 0
README 10장의 “한다”기록 · 분류 · 조회 · 리포트 · 예산 경고 · 감사 로그
모든 AI 호출이 남는다감사 화면에 다섯 자리
숫자를 잰다평가 전부를 한 번에 돌린 표
하지 않는 것CHANGELOG에 이유와 함께

평가 전부를 한 번

명령재는 것
make eval카테고리 고르기
make eval-chat도구 · 기간 · 숫자 · 거절 · 조문
make eval-docs · eval-qa문서 찾기 · 인용하는 답
make eval-insights스펙 · 숫자 · 금지어 · 평범한 달
make eval-capture기록 문장 → 제안

다음 사람이 “좋아졌나”를 물을 기준선입니다

찍기

git flow release start 1.0.0
# VERSION, CHANGELOG — 업그레이드 절: 마이그레이션, 서비스 mcp,
# INSIGHT_MAX_TOOL_CALLS · MCP_*, 평가 표, 하지 않는 것
make all
make review BASE=main
git flow release finish 1.0.0
git push origin main develop --tags

v1.0.0에서 하지 않는 것: 배포, MCP 쓰기, 대화로 수정 · 삭제 · 예산, 규칙 승격, 스트림 재연결, 다중 사용자

git diff v0.7.0 v1.0.0

늘어난 것늘어나지 않아야 하는 것
마이그레이션 하나, 엔드포인트 몇 개LanguageModel 포트의 메서드
mcp 서비스mcp의 LLM 키와 프롬프트
화면 하나 (/runs)SSE 이벤트 종류
평가 세트 둘운영 로그의 칸

라이브에서 눈여겨볼 것

자리증상처방
감사 로그운영 로그에 발화를 찍는다새지 않는지 보는 테스트
상황 통계스펙에 값 배열을 넣는다스키마에 값 칸이 없다
상황 통계숫자 검사를 새로 만든다number_check를 다시 쓴다
채팅 기록ReAct 루프로 만든다단발 + 확인 게이트
채팅 기록확인되면 ui가 api를 부른다확인은 agent로
MCPagent를 import한다먼저 제안하고 멈추게
감사 화면원본 JSON을 쏟는다요약, 원본은 한 번 더 펼쳐서

내 프로젝트로

세 체크리스트

감사 로그쓰기를 열기 전MCP를 열기 전
AI 호출 한 번이 한 줄로 남는가확인 전에는 쓰지 않는가나가는 것을 표로 적었나
운영 로그에 원문이 없는가확인이 흐름의 상태인가기본값이 꺼짐인가
실패하면 무엇이 멈추나멱등 키가 있는가목록 밖은 안 보이는가
12주차 평가 로그가 여기서 나오나취소 · 만료를 처리하나보장하는 선을 적었나

오늘이 남기는 것

  • 남기기: 남기는 것을 먼저 깔고 기능을 얹는다. 운영 로그와 감사 로그는 다르다
  • 계획 실행: 훑고 나서 계획한다. LLM은 숫자 대신 참조를 낸다
  • 쓰기: 확인은 루프가 멈추는 자리다. 제안은 흐름의 단계다
  • 대역 교체: 대역이 하던 것을 진짜가 다 하는지 줄 단위로 맞댄다
  • 밖으로: 표면은 하나 더 열면 된다. 무엇이 나가는지부터 적는다

라이브 빌드 세 편을 한 장으로

flowchart LR
    D["문서 먼저"] --> S["AI 없이 도는 가계부"]
    S -->|"v0.5.0"| T["도구 · ReAct"]
    T -->|"v0.6.0"| R["RAG"]
    R -->|"v0.7.0"| A["감사 로그"]
    A --> P["계획 실행"]
    P --> W["쓰기 · 확인"]
    W --> M["MCP"]
    M --> V["감사 화면"]
    V -->|"v1.0.0"| E(["각자의 프로젝트로"])

문서가 먼저 서고

AI 없이 도는 제품이 서고

AI는 마지막에 들어옵니다

각자의 프로젝트도 이 순서로 갑니다

슬라이드
1 / 1