사내에서 큰 리팩토링 두 건이 동시에 진행됐습니다. 하나는 학생 등록과 클래스 이동, 다른 하나는 클래스에 따른 진도와 과제였습니다. 공교롭게도 이 둘은 독립적이지 않고 의존적인 관계를 갖고 있었습니다. 학생의 클래스 이동이 발생하면 이동한 날짜를 기준으로 각 클래스에 맞는 진도와 과제 데이터가 반영되어야 했습니다. 하지만, 실라버스, 클래스, 트랙 조합에 따른 케이스가 워낙 많아 데드라인 안에 모든 케이스를 테스트하는 건 사실상 불가능했습니다. 배포 버튼을 누르면서도 찝찝한 기분이 남을 수 밖에 없었습니다.
예상했던 대로 자잘한 이슈들이 발생하기 시작했습니다. 진도와 과제 자체의 문제라기보다는 학기 중에 클래스를 이동한 학생의 데이터 불일치와 중복이 원인이었습니다. 근본 원인을 찾아 고치는 게 당연하지만, 과제마다 데드라인이 있어 학생들의 불편함을 빠르게 해소해줘야 하는 것이 급선무였습니다. 하지만 수업은 개발자들이 퇴근한 뒤인 밤 10시까지 진행되어 바로 대응이 불가능한 경우도 발생했으며, 초반엔 빈도도 생각보다 많아서 출근해서도 개발자가 hotfix에 매달리느라 계획된 업무를 못 하는 날이 반복됐습니다.
해결책이 필요했습니다. 이슈를 대응하다보니 패턴이 보였습니다. 대부분의 이슈는 위험도는 낮고, 반복적인 작업이라 사람이 붙어 있을 필요가 없다고 판단하여, OpenClaw로 자동화할 수 있겠다는 생각이 들어 팀에 제안을 했습니다.
사내에서 사용하지 않는 맥북 한 대로 설치를 시작했습니다. LLM 모델을 연결하고 Slack 연동을 통해 사내 워크스페이스에 앱을 추가했습니다. 코딩 작업을 위임할 예정이었기에 주요 레포를 모두 내려받고 CLI 로그인(aws, vercel, gh, docker)까지 마쳤습니다. skills.sh에서 평소 도움이 됐던 next-best-practices, vercel-react-best-practices 같은 공용 스킬도 내려받으며 설정을 마무리했습니다.
준비를 마치고 기대되는 마음으로 Slack을 통해 간단한 태스크를 통해 테스트를 진행했습니다. 하지만, 결과는 기대 이하였습니다. 아무 맥락을 가지고 있지 않은 초기 OpenClaw는 작업 내용을 파악하는 데만 한참 걸렸고 권한이 있어 충분히 가능한 일을 불가능하다고 했으며, 결국 제대로 된 아웃풋을 내지 못했습니다. 당장 업무를 맡길 수 있는 수준이 아니었습니다.
맥락이 없는 에이전트일수록 도메인 지식, 코드베이스, 비즈니스 로직을 처음부터 혼자 파악해야 합니다. 시간은 배로 걸리고, 정확도는 떨어질 수 밖에 없습니다.
하지만, 이건 단순히 에이전트만의 문제가 아니었습니다. AI 에이전트가 업무 전반에 도입되고 수개월이 지나면서, 각자가 쌓아온 노하우와 스킬이 저마다의 로컬에 흩어져 있었습니다. DB 쿼리 하나를 다루는 방식도 사람마다 달랐고, 심지어 에이전트가 DB 쿼리를 할 수 있다는 사실 자체를 모른 채 직접 수동으로 돌리고 있는 팀원도 있었습니다.
나아갈 방향은 명확했습니다. 서비스 공용 지식 허브와 에이전트가 작업하는데 도움을 주는 스킬들, 에이전트들을 한 곳으로 모아서 관리하기로 했습니다. 모두가 이 상황에 공감하며 작업의 필요성을 느낀 덕분에 일주일 정도의 시간을 벌 수 있었습니다.
가장 먼저 무엇을, 그리고 어떻게 담을지 정해야 했습니다. 스타트업 특성 상 모든 태스크들이 꼼꼼하게 문서화가 되어있는 형태는 아니다보니, 분산되어 있는 여러 도메인 정보를 한 곳으로 모으려는 작업은 생각보다 단순하진 않았습니다. 문서 관리의 큰 틀을 만들고, 꾸준히 유지보수하면서 관리하기로 방향을 잡고 산출된 TOPIA Docs의 큰 흐름은 다음과 같았습니다.
1docs/2|-- AGENTS.md 에이전트 진입점3|4|-- rules/ 문서 작성 및 운영 규칙 (governance layer)5| |-- writer/ Writer Agent 기준 규칙6| `-- operator/ Operator 실행 기준 문서7|8|-- overview/ 회사 전체 시스템 맥락을 설명하는 공통 문서 (knowledge layer)9| |-- project-map/ 전체 repo 지도와 연결 관계10| |-- db-schema/ DB 구조와 핵심 테이블 인덱스11| |-- workflow/ 기능별 workflow 문서12| |-- deprecation-policy/ 폐기 및 전환 정책13| |-- glossary.md 용어집14| |-- domain-map.md 도메인 지도15| `-- data-ownership.md 데이터 ownership / source of truth16|17|-- projects/ 각 repository의 역할과 source-of-truth 탐색 진입점 문서 (navigation layer)18| |-- template/ 프로젝트 문서 템플릿19| `-- <project-name>/ 프로젝트별 개요 / URI / 인프라 / 브랜치 매핑20|21`-- skills/ AI agent가 실제 작업 수행 시 사용하는 실행 스킬 (execution layer)22 |-- AGENTS.md 공통 스킬 라우터23 |-- template/ 스킬 템플릿24 `-- <skill-name>/ 공통 스킬 정본TOPIA Docs Architecture
로컬에서의 작업 환경이 모두 다른 것을 고려하여 각자 에이전트의 인덱스 파일(CLAUDE.md, AGENTS.md 등)에서 TOPIA Docs의 AGENTS.md 파일을 바라보게 하는 것으로 설계를 시작했습니다. AGENTS.md 파일에는 작업의 성격에 따라 관련된 파일을 볼 수 있도록 하는 인덱싱 규칙을 위주로 적어뒀습니다. AGENTS.md 파일은 길면 길수록 효율이 떨어지기 때문입니다.
서비스의 전체 흐름을 잡는 overview를 시작으로, 도메인 지식, 우리 서비스에서 쓰이는 용어, 레거시 코드와 엮여 있어 코드만 보면 헷갈리는 정책들, 그리고 기록해두지 않으면 알 수 없는 DB 접근 방법과 여러 규칙들을 스킬로 만들어서 채워 나갔습니다. 추후에 하네스 엔지니어링에 도움이 되는 각 tool을 장착한 에이전트들을 추가해 나갈 계획입니다.
전반적인 설계는 단독으로 진행했으나, 프론트엔드 개발을 주로 하고 있던 저로써는 전체 문서를 완성하는 게 불가능했고, 다행히 팀원분들이 도움을 많이 주셔서 완성할 수 있었습니다. 이젠 다시 오픈클로를 테스트해볼 차례였습니다.
간단한 DB 수정 요청 작업이나 수정 범위가 예상이 되는 프론트엔드 코드 수정을 오픈클로에게 부탁했습니다. 이전에는 불가능했던 DB 접속을 통한 맥락 파악이 가능해졌고, 큰 맥락 파악이 필요하지 않은 UI 코드변경 요청은 그럴싸하게 작업을 마무리했습니다. 큰 작업 단위를 위임하는 것은 여전히 무리지만, 사람이 로컬에 접속하여 직접 작업이 불가능한 상황에서 문제 상황을 파악하고 긴급하게 대처하기에는 훌륭한 수준까지 도달했다고 생각합니다.
실제로 오픈클로 hotfix 에이전트가 팀에 합류하고 자리를 잡은 후, 팀원분들이 퇴근하면서 간단한 작업들을 위임하여 진행하는 모습들이 꾸준히 보이고 있으며, 이에 뿌듯함을 느낄 수 있었습니다.
하지만, 이는 언제까지나 잘 관리되고 있는 문서일 때 보장될 수 있는 성과였습니다. 당장 작업을 해둔 따끈따끈한 문서이므로 지금은 문제가 발생하지 않겠지만, 시간이 흐르고 작업이 추가/수정됨에 따라 이 문서 또한 동기화된 상태를 유지해야 하는데, 이것이 또 하나의 큰 문제점이었습니다.
사람이 코드의 모든 수정 내용을 정리해서 문서에 수동으로 업데이트하는 작업은 분명 시간이 가면서 지치게 되고, 실수로 인해 누락이 발생할 수 밖에 없습니다. 따라서, 에이전트를 통한 자동화가 반드시 동반되어야 하다고 생각했습니다.
이 또한 방향성은 명확했습니다. 코드 수정이 진행되는 모든 레포와 TOPIA docs 레포를 연동시켜서 변경사항을 파악하여 갱신할 수 있도록 설계를 해야 했습니다. 설계한 방향은 다음과 같습니다.
각 서비스 레포에서 prod 브랜치에 코드가 푸시되면, GitHub Actions가 자동으로 utopia-doc 레포에 알림을 보내고, AI(GPT-4.1)가 diff를 분석해서 문서 정본을 최소 범위로 갱신하는 시스템입니다.
1┌─────────────────┐ repository_dispatch ┌──────────────┐2│ source repo │ ─────────────────────────▶ │ TOPIA docs │3│ (prod push) │ "코드 바뀌었어" │ (hub) │4│ │ │ │5│ notify-utopia- │ │ doc-sync- │6│ doc.yml │ │ hub.yml │7└─────────────────┘ └──────┬───────┘8 │9 ▼10 ┌──────────────┐11 │ doc_sync_ │12 │ hub.py │13 │ │14 │ 1. diff 계산 │15 │ 2. AI 분석 │16 │ 3. 문서 수정 │17 │ 4. commit │18 └──────────────┘전체 흐름
일주일 정도 테스트를 돌려봤습니다. 간단한 코드 변경에 맞춰 문서가 수정되는 것까지는 가설대로 동작했습니다. 하지만 이 시스템을 믿고 문서 관리를 통째로 맡기기에는 한참 부족했습니다.
결국 "사람은 코드만 고치고, AI가 알아서 문서를 맞춰준다"는 그림은 무리였습니다. 사람끼리도 도메인 지식을 완전히 공유하기 어려운 상황에서, AI가 코드가 아닌 사람 사이의 대화에서 오는 맥락까지 파악하길 기대한 건 욕심이었습니다. 나아가 앞으로 이게 가능해질지도 솔직히 잘 모르겠습니다.
그래도 공용 문서를 만든 이상 관리는 계속되어야 하고, 사람이 직접 문서를 쓰는 건 워크플로에서 큰 병목이 됩니다. 다른 방법이 필요했는데, 의외로 간단했습니다.
TOPIA docs 레포에 에이전트를 하나 추가해서, 코드를 푸시하기 전에 변경사항에 맞춰 문서 수정을 먼저 하도록 워크플로에 끼워 넣은 겁니다. 코드를 푸시한 뒤 AI가 사후에 추적하는 게 아니라, 개발자가 작업하는 흐름 안에서 문서 업데이트가 함께 일어나도록 순서를 바꾼 것입니다. 공들여 만든 TOPIA docs는 이 방식으로 꾸준히 관리되어 오고 있습니다.
25년 말 에이전트 AI가 빠르게 발전하고, 26년 초 OpenClaw 같은 시스템이 등장하면서, 그동안 불편하다고만 느꼈던 것들을 에이전트로 풀어보려는 시도가 곳곳에서 나오고 있습니다. 어떤 팀은 AI의 한계를 근거로 회의적인 입장을 취하고, 비슷한 문제를 AI로 해결했다는 곳도 있어서, 한쪽 이야기만 듣고 판단하기는 어렵습니다.
저희 팀에서 느낀 건 이겁니다. AI에게 전부를 맡기려 했을 때는 실패했지만, 사람의 워크플로 안에 자연스럽게 끼워 넣었을 때는 동작했습니다. 완벽한 자동화보다는, 사람과 에이전트가 각자 잘하는 영역을 나눠 갖는 구조가 현실적이었습니다. 다음에 비슷한 문제가 생기면 "AI가 다 해줄 수 있을까"보다 "어디까지를 맡기고 어디서 사람이 개입할까"부터 생각하게 될 것 같습니다.