첫 데모에서 검증 가능한 워크플로까지

한국 개발자가 OpenAI 에이전트를 처음 실행한 뒤 마주치는 근거, 권한, 승인, 평가 문제를 작은 제품으로 드러낸 공개 레퍼런스 구현입니다.

문제

첫 모델 출력은 빠르게 만들 수 있습니다. 실제 팀에서는 곧 다른 질문이 생깁니다. 어떤 데이터를 읽었는가, 어떤 도구가 행동할 수 있는가, 근거가 충분한가, 실패를 다음 버전에서 어떻게 막을 것인가. 이 프로젝트는 기능 수보다 그 통제 지점을 다른 개발자가 이해하고 다시 실행할 수 있게 만드는 데 집중했습니다.

구현한 시스템

OpenAI Agents SDK로 만든 한국어 정책 안내 에이전트
합성 승인 문서만 읽는 모델 가시 도구 1개
답변, 근거, 신뢰도, 검토 사유, 후속 제안을 분리한 구조화 출력
외부 행동 도구 0개, 모든 후속 제안은 review_required
질문별 기록 replay mode, 실제 API 실행 경로, 공개 Vercel 배포
한국어와 영어 빠른 시작, 위협 모델, 한계, GitHub Actions 검증

설계 판단

멀티에이전트를 보여주기 위해 억지로 추가하지 않았습니다. 이 워크플로에는 추론 책임자 한 명과 읽기 전용 검색 경계 하나만 필요했습니다. 항상 적용되는 규칙은 AGENTS.md에, 조건부 절차는 네 개의 focused skill에, 반복 실행은 스크립트와 테스트에 두었습니다.

실패가 바꾼 것

첫 오프라인 평가에서 육아휴직 질문이 데이터 취급 정책을 잘못 검색했습니다. 두 문장에 공통으로 있던 ‘사용할’이라는 일반 동사가 가짜 근거를 만들었습니다. 테스트도 실제 사용자 문장을 쓰지 않아 이 실패를 놓쳤습니다. 실제 fixture를 regression test로 옮기고 검색기의 일반 토큰을 분리한 뒤 전체 케이스를 다시 실행했습니다.

사용성 시뮬레이션이 바꾼 것

한국 개발자 페르소나 세 명의 독립된 15분 시뮬레이션에서 질문을 바꿔도 같은 원격근무 답변이 재생되는 결함이 발견됐습니다. 실제 사용자 연구가 아님을 공개 문서에 명시하고, 질문별 replay 세 개, 임의 질문 차단, 재생 배너, 원문 링크, 피드백 저장 설명, 민감정보 경고와 회귀 테스트로 수정했습니다.

현재 검증된 범위

저장소 구조와 Python 문법, 기본 비밀정보 패턴 검사 통과
오프라인 unit test 18개 통과
합성 정책 offline fixture 5개 전부 통과
gpt-5-mini 온라인 agent fixture 5개 전부 통과, OpenAI Agents SDK 0.18.3
설치된 OpenAI Agents SDK에서 에이전트, 도구, 구조화 출력 import 확인
공개 Vercel replay 배포, 질문별 근거 정합성, 로컬 피드백 저장 확인

아직 증명하지 않은 것

5개 합성 케이스의 단일 온라인 실행과 세 개의 AI 페르소나 시뮬레이션은 운영 신뢰성이나 실제 한국 개발자 온보딩을 증명하지 않습니다. 적대적·held-out 평가와 실제 clean-machine 사용자 세션은 별도 검증 단계입니다. 이 예제를 개인정보보호 또는 보안 준수 사례로 표현하지 않습니다.

Developer Experience 관점

제가 만들고 싶은 개발자 경험은 에이전트를 더 크게 보이게 하는 것이 아닙니다. 다른 개발자가 무엇을 믿고 무엇을 검토해야 하는지 이해한 채 첫 호출에서 반복 가능한 워크플로로 갈 수 있게 하는 것입니다. 사용자가 막힌 지점을 코드, 문서, 예제, 평가 중 올바른 층으로 되돌려 보내는 것까지 제품의 일부로 봅니다.