AI 에이전트 프로젝트, 대시보드 대신 ADR+Roadmap으로 굴렸다

요즘 AI 에이전트 팀들 보면 대시보드 만들어가면서 진행하는 방식이 유행이다. 멋지고 보기 좋고, 팀 안팎으로 공유하기도 편하다.

장점은 인정한다. 근데 가만 보면, 대시보드가 관리하는 게 결국 뭔가 싶었다. 어떤 결정을 했고, 지금 뭘 해야 하고, 어디까지 왔는지. 그거 결국 ADR이랑 Roadmap 아닌가?

차이가 있다면 그걸 "불필요하게 많은 에이전트가 대시보드라는 형태로" 돌린다는 거다. 배경 context를 세션마다 각자 읽고, 상태를 계속 쓰고, 그 비용이 토큰으로 쌓인다. 거기다 아직은 에이전트들이 대시보드에 올릴 만큼 구조화된 판단을 알아서 내려줄 정도는 아니었다.

그래서 이번에 새 프로젝트를 시작하면서, 대시보드부터 만드는 대신 그동안 개발하면서 효율적이라고 느꼈던 방식들을 명문화해서 도입해보기로 했다.

이 프로젝트가 뭔데

우리 스타트업에는 여러 서비스가 있다. 이 프로젝트의 목표는 그 서비스들을 AI 에이전트가 실제로 쓸 수 있는 형태로 만드는 것이다.

근데 단순히 "API 붙이고 딸깍" 하면 끝나는 게 아니다.

서비스마다 phase가 다르고, 아직 스펙이 안 정해진 서비스도 있고, 지금 당장 정보 다 주고 돌리면 1시간 만에 뭔가 나오긴 하겠지만, 그런 식으로 만들면 유지보수가 개떡이 된다. 안정성도, private key나 secret 관리도, 검증도 안 되고.

그래서 개발 방향을 처음부터 잡았다.

SKILL-first, 이후 MCP-hardening.

이유는 현실적이다.

• MCP는 실행을 코드로 고정하니까 완결성과 실수 최소화에 강하다. 근데 context를 많이 먹고, 설치/운영 난이도가 있다.
• SKILL은 평문이라 초기 도입과 확장이 빠르다.
• 그래서 기본은 SKILL로 가되, 최소한 action entry를 명시해서 실행 경로만큼은 고정한다. 어떤 intent가 들어오면 어떤 executor entrypoint를 호출하는지, 그 라우팅은 확실히 잡아두는 거다.
• 이후 SKILL만으로는 품질이 부족해지는 구간부터 MCP를 붙여서 실행을 코드화하고, 실수 방지 수준을 끌어올리는 방향으로 간다.

즉 SKILL vs MCP가 아니라, SKILL로 시작해서 MCP로 하드닝하는 단계적 전환을 전제로 설계했다.

개발은 어떻게 굴렸나

작은 AI 루프 + 큰 루프

이 프로젝트는 AI 에이전트끼리 개발하는 프로젝트다 보니까, 루프를 두 겹으로 돌렸다.

작은 AI 루프:

1. Codex가 먼저 결정안이나 초안을 만든다.
2. Claude가 피드백한다.
3. Codex가 반영한다.

큰 루프(사람 포함):

1. 내가 의도, 우선순위, 리스크를 최종 피드백한다.
2. 세 주체가 합의되면 PR을 연다.

이건 ADR 작성에만 쓴 게 아니라 구현에도 같은 방식으로 적용했다. 결국 중요한 건 "누가 더 똑똑하냐"보다 "같은 실수를 줄이는 반복 구조가 있느냐"였다.

개발용 SKILL

ADR 쓰고, ADR 기반으로 구현하고, PR 올리고. 이 과정이 반복되니까 에이전트가 슬슬 멍청해지기 시작한다. 맥락 빠뜨리고, 포맷 흐트러지고, 빠져야 할 게 빠지고.

그래서 개발 프로세스 자체를 SKILL로 만들었다.

• ADR 생성: 어떤 scope일 때 ADR을 써야 하는지, 템플릿은 뭔지, 어디에 놓는지
• ADR 기반 실행: accepted된 ADR이 있으면 바로 구현 모드로, 없으면 먼저 ADR 작성 모드로
• PR 준비: 메타데이터 포맷, 동기화 체크, 변경된 파일에 따라 어떤 검증을 돌릴지

이건 프로젝트의 "산출물"이 아니라, 프로젝트를 "운영"하기 위한 SKILL이다. 에이전트가 항상 반복하면서 멍청해지지 않게 만드는 최소한의 가이드라인 같은 것.

산출물 SKILL의 검증 문제

여기서 좀 다른 맥락의 문제가 있었다.

프로젝트가 만드는 산출물, 그러니까 각 서비스를 AI 에이전트가 쓸 수 있게 정의한 SKILL들. 이것들은 평문이다. 코드처럼 컴파일이나 타입체크가 안 된다.

그리고 여러 서비스에 붙이다 보니 변형이 많아진다. 거기다 연결해야 하는 product API가 아직 고정되지 않아서 수시로 바뀔 위험이 상시 존재한다.

정리하면 이런 상태다.

• 평문 SKILL은 "디버깅"이 안 된다. 사람이 매번 전부 읽고 확인하는 건 금방 한계가 온다.
• API가 바뀌면 SKILL과 실행 흐름이 쉽게 어긋나는데, 그걸 눈으로 잡는 건 비현실적이다.
• 서비스가 늘수록 이 문제는 곱으로 커진다.

그래서 "완벽한 통제"가 아니라 "최소한의 생존 장치"로 검증을 붙였다.

지금은 SKILL마다 세 가지를 한 세트로 관리하고 있다.

1. SKILL 정의: 에이전트가 읽고 실행하는 평문 파일
2. 최소 스펙 문서: 이 SKILL이 반드시 포함해야 하는 항목 정의 (action entry, 필수 파라미터, 에러 케이스 등)
3. 검증 스크립트: 스펙 기준으로 SKILL을 자동 체크하는 코드

대충 이런 느낌이다:

REQUIRED_ACTIONS = ["create-user", "update-profile", "delete-account"]
REQUIRED_FIELDS  = ["action_entry", "parameters", "error_handling"]

def validate(skill_file):
    skill = load_skill(skill_file)
    missing_actions = [a for a in REQUIRED_ACTIONS if a not in skill.actions]
    missing_fields  = [f for f in REQUIRED_FIELDS if f not in skill.metadata]
    exposed_secrets = scan_for_secrets(skill.content)
    return missing_actions, missing_fields, exposed_secrets

이 셋이 항상 같이 움직이니까, SKILL이 바뀌면 스펙이 맞는지 자동으로 걸리고, 스펙이 바뀌면 검증도 따라 바뀐다.

처음엔 나도 action entry 누락, 필수 메타데이터, 시크릿 노출 정도만 체크했다. 근데 진행하면서 AI가 추가 제안을 붙이기 시작했다. intent 목록이 실제 서비스 계약이랑 맞는지 대조하는 거, 테스트 벡터에 마커가 다 있는지 확인하는 거, 파일이 바뀌면 연관된 동기화 그룹을 같이 업데이트했는지 체크하는 거. 그걸 하나씩 받아들이다 보니 검증 로직이 점진적으로 구조화됐다.

결과적으로 개발 속도만 높이는 방식보다 운영 안정성 쪽에서 이득이 컸다. 처음부터 전부 설계한 게 아니라, 필요한 만큼 붙이다 보니 자연스럽게 쌓인 거다.

ADR과 Roadmap을 분리한 이유

운영 방식도 비슷한 이유로 바뀌었다.

처음엔 1 ADR → 1 구현 PR로 맞추려고 했다. 결정 하나에 구현 하나. 깔끔하잖아.

근데 실제로는 ADR이 결정 단위로는 크고 무거워서, 구현 단위와 1:1로 항상 맞지 않았다. 하나의 ADR에서 나오는 구현이 여러 개이거나, 반대로 여러 ADR의 결정이 하나의 구현에 겹치거나.

그래서 역할을 분리했다.

• ADR: 왜 이 결정을 했는지 고정. 근거의 영역.
• Roadmap: 어떤 순서와 크기로 실행할지 관리. 실행의 영역.

이렇게 바꾸고 나서 체감이 좋아졌다. 결정은 덜 흔들리고, 실행은 더 작고 쾌적해졌다. ADR이 무거워서 PR이 묶이는 일도 없어졌고.

정리하면

이 프로젝트는 대시보드를 부정한 게 아니다.

다만 내 상황에서는 대시보드보다 먼저 고정해야 할 것들이 있었다.

• 결정은 ADR로
• 실행은 Roadmap으로
• 반복 품질은 SKILL 기준과 최소 검증으로

그리고 그 다음 단계에서 MCP를 붙여 실행을 코드화하고 완결성을 끌어올리는 방향으로 간다.

결국 이번 프로젝트에서 중요했던 건 "결과물을 빠르게 만드는 능력"보다 "결과물이 계속 유지되게 만드는 규율" 쪽에 더 가까웠다.

아직 완성된 정답이라고 보긴 이르다. 근데 적어도 지금까지는, "딸깍 생산성"보다 "반복 가능한 품질"에 더 가까운 방식으로 돌아가고 있다.

프로젝트 더 진행하고 나서 다음 편 써볼 예정.

물론 context window가 지금보다 훨씬 방대해지고, "1%의 인간 판단"마저 진짜 대체 가능해지는 시점이 오면 이야기가 달라질 수 있다. 최근 Fujitsu가 AI 개발팀 서비스를 시작한다는 소식도 나왔는데, 저건 대시보드든 뭐든 체계화된 운영 도구를 전제로 깔고 가는 방향이다. 지금은 나 같은 원맨팀한테는 과한 구조지만, 저런 서비스가 보편화되면 대시보드 방식도 실용적인 선택이 될 수 있겠다.

근데 지금은 아직 아니었고, 그래서 이 방식을 택했다.

추신. 이 글 자체가 좀 웃긴 과정을 거쳤다. 처음에 Codex한테 블로그 글을 써달라고 했다. 코드는 진짜 잘 쓰는 모델인데, 한국어 글쓰기가 문제인 건지 글 자체를 못 쓰는 건지, 내 말귀를 도통 못 알아먹었다. 19번을 피드백 줬는데도 맥락을 계속 놓쳤다.

결국 포기하고, "내가 한 말들을 conversation.md로 정리해"라고 시켰다. 그건 잘 했다. 그다음에 그 conversation 파일이랑 Codex가 만든 draft를 Claude Code한테 넘겼더니, 진심 딸깍 하고 이번 글이 나왔다.

돌이켜보면, 본문에서 말한 AI 루프를 블로그 글쓰기에 쓸 생각은 전혀 없었다. 근데 Codex가 초안 만들고, Claude가 정리하고, 내가 최종 피드백하는 과정이 결국 그대로 AI 루프였다. 의도 없이 돌아간 셈이다.

에이전트별 잘하는 게 다르다는 것도, 글 쓰는 과정에서 그대로 체험했다.