에이전트를 도입하고 나서 팀이 가장 먼저 맞닥뜨리는 벽은 모델 성능이 아니다. '이게 왜 이렇게 동작했지?'라는 질문에 아무도 답하지 못하는 상황이다. 격리 모델을 짜고, 권한 범위를 정하고, 거버넌스 게이트를 세웠다고 해도—에이전트에게 무엇을 지시하고, 완료 기준을 어떻게 정의하는가라는 앞단 설계가 빠지면 워크플로우 전체가 흔들린다. 오늘은 그 앞단을 세 가지 입력 구조로 정리한다.
1. 시스템 프롬프트: 팀의 것이어야 한다
Dev.to에 기고된 Jean2 개발자의 글은 불편한 사실 하나로 시작한다. Claude Code, Cursor, Copilot—모든 주요 AI 코딩 에이전트는 숨겨진 시스템 프롬프트를 내장하고 있다. 잘 만들어진 프롬프트다. 모델을 잘 아는 사람들이 썼다. 하지만 팀의 것이 아니다.
문제는 세 가지로 구체화된다. 첫째, 에이전트가 예상 밖 행동을 해도 원인을 추적할 수 없다. '항상 pnpm을 써라'라고 지시했는데 npm을 쓴다면? 내장 프롬프트 어딘가에서 충돌이 일어나고 있는 거지만, 볼 수 없으니 디버깅이 불가능하다. 둘째, 원하지 않는 동작을 제거할 수 없다. 매 변경 후 자동 테스트 실행, 커밋 제안—내장된 행동은 끌 방법이 없다. 셋째, 모델의 판단인지 제품의 스티어링인지 구분이 안 된다. 특정 라이브러리를 추천한 게 진짜 좋아서인지, 프롬프트에 박혀 있어서인지 알 수 없다.
Jean2가 제안하는 해법은 개념적으로 단순하다. 기본 시스템 프롬프트를 없애고, 팀이 직접 조립하게 한다. 구조는 이렇다: Preconfig(핵심 에이전트 설정) → AGENTS.md(워크스페이스별 프로젝트 지시사항) → Workspace MEMORY.md(학습된 프로젝트 사실) → Agent USER.md(개인 선호) → Skill 파일(배포 체크리스트, 코드 리뷰 기준). 이 레이어가 전부 디스크 위의 파일이다. 읽을 수 있고, 수정할 수 있고, 버전 컨트롤에 들어간다.
현장 적용 관점에서 이게 의미하는 건 하나다. 지금 당장 Claude Code나 Cursor를 그대로 쓰더라도, 팀이 관리하는 AGENTS.md 파일 하나를 워크스페이스 루트에 두는 것으로 시작할 수 있다. 빌드 명령어, 코드 스타일, '하지 말아야 할 것' 목록—이게 버전 컨트롤에 들어가는 순간, 팀 전체가 동일한 맥락 위에서 에이전트를 돌리게 된다. Jean2 방식의 완전 투명성에 동의하지 않더라도, 팀이 관리하는 컨텍스트 레이어를 갖는다는 원칙은 지금 쓰는 도구에도 적용된다.
2. Done-When 정의: '완료'는 감정이 아니다
Marcus Kim이 Dev.to에 쓴 글의 첫 문장은 팀 리드라면 붙여 두고 싶은 문장이다. "Finish is a mood. It is not a requirement." '프로필 화면 완성해줘'라는 요청을 에이전트에게 던지면, 에이전트는 바빠진다. 필드를 추가하고, 간격을 맞추고, 유효성 검사를 쓴다. 그리고 완료했다고 말한다—레벨 확인 없이 선반을 단 사람처럼 자신 있게.
화면이 존재한다고 기능이 동작하는 게 아니다. 실제 사용자가 프로필을 만들고, 앱을 닫고, 다시 열었을 때 데이터가 남아 있는가? 이미 다른 계정에 쓰인 이메일을 입력하면 어떻게 되는가? 저장 도중 네트워크가 끊기면? 에이전트는 이 질문들을 스스로 만들어내지 않는다. 요청에 없으면 없는 거다.
Done-When 정의는 이 공백을 메우는 한 문장이다. 구조는 네 가지 질문에 답하는 것이다. 누가 하는가(사용자 상태와 권한), 무엇을 하는가(실제로 수행 가능한 동사 하나), 무엇이 바뀌거나 유지되어야 하는가(저장, 반영, 동기화), 어떻게 증명할 것인가(QA 체크리스트).
구체적인 예시가 이해를 돕는다. 'RSVP 기능 만들어줘' 대신 이렇게 쓴다: 로그인한 사용자가 이벤트를 열어 '참가'를 선택하면, 앱을 재시작한 후에도 RSVP가 저장된 상태로 보이고, 저장 실패 시 유용한 오류 메시지가 표시된다. 이게 Done-When이다. 이 문장이 있으면 에이전트가 이벤트 생성, 초대장, 캘린더 동기화, 배지 시스템까지 만들어내는 걸 막는 명분이 생긴다.
Marcus Kim이 제안하는 프롬프트 구조는 그대로 팀 템플릿으로 쓸 수 있다. 에이전트에게 기능을 지시하기 전에: ①워크플로우를 평문으로 재진술해라, ②필요한 화면/데이터/권한/연동을 나열해라, ③이번 버전의 스코프 밖을 명시해라, ④Done-When을 검증하는 QA 체크리스트를 줘라, ⑤공유 스키마/인증/결제에 손대기 전에 승인을 구해라. 그런 다음 Done-When을 만족하는 가장 작은 버전만 구현해라. 에이전트가 관련 없는 대시보드나 알림 시스템을 추가하기 시작하면, 돌아올 기준이 생긴다: '이게 Done-When을 만족시키는가?'
3. 두 입력이 맞물릴 때 생기는 것
시스템 프롬프트 투명성과 Done-When 정의는 별개의 기법처럼 보이지만, 실은 같은 문제의 두 면이다. 전자는 에이전트가 어떤 맥락 위에서 동작하는지를 팀이 소유하게 하고, 후자는 그 맥락 안에서 무엇을 만들어야 끝인지를 명확하게 한다. 이 두 입력이 없으면, 에이전트는 계속 '완료했다'고 보고하고 팀은 계속 그게 왜 문제인지 설명하느라 시간을 쓴다.
AI 코딩 에이전트의 ROI가 기대에 못 미치는 팀을 들여다보면 공통점이 있다. 에이전트의 동작 원인을 추적할 수 없거나, 에이전트에게 넘긴 작업의 완료 기준이 없거나, 혹은 둘 다다. 속도는 오르는데 재작업이 줄지 않는다면 도구 문제가 아니라 입력 설계 문제다.
내일 당장 할 수 있는 것부터 정리하면 이렇다. 워크스페이스 루트에 AGENTS.md를 만들고 빌드 명령어, 코드 스타일, 금지 행동을 적어라. 다음 기능 티켓에 Done-When 한 줄을 추가해라. 이 두 가지만으로도 에이전트 워크플로우의 예측 가능성이 올라간다. 완전한 시스템 프롬프트 투명성은 Jean2 같은 도구로 더 깊이 파고들 수 있지만, 시작은 파일 하나와 문장 하나로 충분하다.