Kunsang Lee

Kunsang Lee

이건상 · AI 에이전트를 만들고, 그 에이전트가 일하기 좋은 코드 구조를 설계합니다

동료와 같은 에이전트

Slack 에서 부르면 코드베이스와 데이터베이스를 조회해 근거와 함께 답하고, 티켓과 PR 까지 맡도록 직접 설계했습니다

말뜻을 알아듣고 기억하는 에이전트

평소 말투로 물어도 모델이 뜻을 읽습니다. 에이전트가 듣는 채널의 글을 임베딩으로 쌓아 두고, 필요할 때 뜻이 가까운 지난 대화를 찾아 답에 씁니다

집중은 그대로, 답은 바로

담당자가 하던 일을 멈추지 않아도 되도록, 그 사람이 답했을 질문을 에이전트가 먼저 받아 근거와 함께 답하게 했습니다. 15주 동안 질문 절반은 96초 안에 첫 답을 받았습니다

담당자가 잠든 시간에도

담당자를 기다리지 않아도 답을 받을 수 있게 했습니다. 근무 시간 밖에 올라온 질문 39건도 절반은 99초 안에 첫 답이 달렸습니다

문서로 권하던 규칙을 검사로

직접 만든 오픈소스 도구 ai-ready 는 문서로만 권하던 규칙 가운데 막을 수 있는 것을 lint·테스트 같은 검사로 옮깁니다. 리뷰에서 바로잡은 실수도 막을 수 있으면 승인을 거쳐 검사로 옮겨, 같은 지적을 두 번 하지 않아도 됩니다

옆 코드만 따라 해도 맞도록

Agent-Friendly Architecture. 외부 연동마다 같은 틀의 기능 폴더를 두어 옆 폴더를 따라 만들면 되게 했고, 지켜야 할 규칙은 테스트로 옮겨 push 전에 검사합니다

에이전트를 만들고 계신가요?

만들면서 겪은 일을 나누고 싶습니다

01대표 작업 · agent-colleague

Slack 에서 일하는 사내 AI 에이전트

처음 만든 봇을 TypeScript 와 Claude Agent SDK 로 다시 설계했습니다. 비결정론적인 판단은 모델에, 실행해도 되는지 같은 결정론적인 판단은 코드에 맡겼습니다. 여기서는 에이전트에게 무엇을 맡기고 무엇을 막았는지, 코드를 어떻게 고치게 했는지를 적었습니다.

  1. 쓰기는 사람이 답한 뒤에

    티켓 생성 같은 쓰기 도구는 봇이 스레드에 글을 올린 뒤 사람이 답했을 때만 실행되고, 실행 기록을 확인해 같은 요청을 두 번 실행하지 않습니다.

  2. 고친 코드는 리뷰를 거쳐서

    격리된 작업 공간에서 구현하고, 수정 권한이 없는 별도 리뷰 세션이 찾은 문제를 반영한 뒤 봇 전용 브랜치에서만 PR 을 엽니다.

  3. 운영 DB 는 읽기만, 개인정보는 빼고

    개인정보 컬럼을 읽지 못하는 계정으로만 조회하고, 쓰기는 거부하며, 실행 계획으로 비용을 재서 무거운 조회는 사람이 답한 뒤에 실행합니다.

02

15주 동안의 기록

  • 96초

    질문 절반이 첫 답을 받기까지 걸린 시간. 근무 시간 밖에 올라온 39건은 99초였습니다

  • 하루 약 30분

    업무 질문마다 누군가 하던 일을 멈추고 답했다면 들었을 시간

2026년 6월 10일~9월 22일, 팀 코드 질문 채널의 Slack 스레드를 직접 센 기록입니다. 이 기간 대부분은 재설계 전의 첫 봇이 답했고, 답이 맞았는지는 재지 않았습니다. 하루 약 30분은 모든 질문에 사람이 바로 답했고 한 건에 10분이 든다고 가정한 추정값이라 실제보다 클 수 있습니다. 계산 과정은 2편에 적었습니다.

03Open Source · MIT

리뷰와 문서로 권하던 규칙을 자동 검사로

에이전트는 문서를 읽고도 규칙을 놓칠 수 있지만, CI 에서 실패하는 lint 규칙은 지나칠 수 없습니다. 문서에만 있는 규칙을 도구로 옮길 수 있는지 따지고, 옮길 수 없는 것만 이유와 함께 문서에 남기도록 돕는 오픈소스 도구를 직접 만들었습니다.

  1. 점검

    문서에 적힌 규칙을 하나씩 보고, 이미 검사로 막고 있는지, 검사로 옮길 수 있는지, 옮길 수 없는지 나눕니다. 판단마다 근거가 된 파일을 함께 적습니다.

  2. 적용

    사람이 고른 규칙만 팀이 이미 쓰는 lint·아키텍처 테스트 도구의 규칙 초안으로 옮깁니다. 이미 어긴 곳은 따로 묶어 두고 새로 어기는 것만 잡습니다.

  3. 교훈

    작업 중 바로잡은 실수와 PR 리뷰 댓글을 모아, 막을 수 있으면 검사 규칙 초안을, 막을 수 없으면 이유를 붙인 금지 목록 항목을 만듭니다. 사람이 하나씩 승인한 것만 반영합니다.

GitHub 저장소kunsanglee/ai-ready(새 탭)

04Agent-Friendly Architecture

근처 파일만 보고 고쳐도 깨지지 않게 짠 코드 구조

AI 코딩 에이전트는 요청 한 줄과 근처 파일 몇 개만 보고 일하고, 가까이 있는 코드를 따라 씁니다. 그렇게 고쳐도 전체가 맞게 돌도록 코드 구조와 자동 검사를 짰습니다. Cursor 의 Lauren Tan 이 영상에서 소개한 Dune 프로젝트 문서를 바탕으로 사내 에이전트 코드에 적용했습니다.

  1. 옆 폴더를 따라 만들면 되게

    외부 연동마다 같은 모양의 기능 폴더를 두었습니다. 새 연동을 붙일 때 세션이나 시작 코드는 고치지 않아도 됩니다.

  2. 지켜야 할 규칙은 테스트로

    기능 폴더가 환경 변수·네트워크를 직접 쓰지 못하게 하는 것 같은 경계 규칙을 테스트로 만들어 push 전에 돌립니다.

  3. 실패하면 고칠 곳을 알려 주게

    경계 테스트의 실패 메시지에 코드를 어디에 둬야 하는지 적어 두어, 에이전트가 그 메시지를 보고 고칠 수 있게 했습니다.

05

만들면서 판단한 것을 씁니다

1편은 다른 파트의 코드를 확인하려고 매번 담당자를 찾아야 했던 불편에서 시작해, 사람 대신 에이전트에게 물어볼 수 있게 만든 이야기입니다. 2편은 15주 동안 얼마나 쓰였는지 돌아보고, 확인을 넘어 티켓과 PR 같은 일까지 맡길 수 있게 에이전트를 다시 설계한 이야기입니다.

에이전트 이야기라면 언제든

만드는 중인 에이전트가 있다면 들려주세요.