AI 서비스 엔지니어링: Track A
9주차 · 라이브 빌드 3: 대역을 걷어내고 v1.0을 찍다
CodeCompose · 2026-10-15
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와 코드만
- 운영 로그에 발화·금액·가맹점이 새지 않는지 보는 테스트를 넣어라 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 응답 + 정해진 도구 응답)로 쓰기 한 번은 두 박자
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 + 예산 페이스 한 줄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 모드에 쓰기 도구가 없다는 테스트는 그대로 통과해야 한다 2회전 · 채팅이 진짜를 부른다
채팅 기록의 마지막 feature다. ui의 기록 쪽을 agent로 바꾸자.
- RoutedChatAgent: 기록 문장도 AgentChatAgent로. decide()는 agent에 전달
- SSE 이벤트는 늘리지 않는다. proposal은 chat.md 4.1에 이미 있다
- 기록 직후 예산 페이스 한 줄을 대역과 같은 모양으로
- 계획에서 만든 평가 세트로 make eval-capture (-m integration)
- stand-ins.md, AI 지도, 위키에서 "기록 쪽은 아직 대역"을 지워라 3부 지시 프롬프트
MCP 서버를 읽기 전용으로 세우자. Refs #<MCP 이슈>
- 읽을 것: docs/ai/mcp.md 전부, tools.md 6장
- 다섯 번째 서비스 mcp. stdio 전송. MCP_TOKEN이 비면 뜨지 않는다
- 허용 목록 기본값은 집계 넷. 목록 밖은 목록 응답에도 없다
- 기간 이름을 푸는 코드와 도구 스키마가 agent에 있다. agent를 import하지 마라.
둘이 같이 써야 하는 것을 어떻게 나눌지 먼저 제안하고 멈춰라
- 호출마다 감사 로그에 seat=mcp로. 클라이언트 이름도
- 분당 호출 상한. 도구 오류는 결과의 오류 플래그로