AI 에이전트 18개로 2021년 글 67편을 병렬 보강한 방법

블로그를 몇 년 운영하다 보면, 옛날에 쓴 강좌 글이 검색에는 걸리는데 내용은 낡아서 손대기 겁나는 상태가 됩니다. 이 글은 그런 글 수십 편을 AI 서브 에이전트로 한꺼번에 고치고 싶은데, 병렬로 돌렸다가 엉망이 될까 걱정하는 분을 위한 기록입니다. 저희는 2021년에 쓴 강좌 글 67편을 모두 검증된 한국어·영어·일본어 글로 보강했고, 마지막 54편은 에이전트 18개를 병렬로 돌려 한 번에 배포했습니다. 잘된 이유는 네 가지뿐입니다. 공통 브리프, 철저한 파일 담당 구분, 모든 에이전트가 통과해야 하는 검증 도구, 그리고 에이전트에게는 맡기지 않은 단 한 번의 병합입니다.

운영 서버를 에이전트에게 맡길 때의 안전장치는 AI 코딩 에이전트에게 운영 서버를 맡겼을 때 실제로 버틴 안전장치에 정리했습니다. 이번 글은 그다음 이야기로, 에이전트 여러 개가 저장소 하나를 같이 쓰면서도 충돌하지 않게 한 방법입니다.

숫자로 본 전체 작업

아래 숫자는 모두 작업 중 도구 출력이나, 나중에 파일을 다시 세어 본 결과입니다.

이 배포 뒤 글 수는 세 언어 모두 86편, 사이트맵 주소는 326개가 됐습니다.

처음부터 18개는 아니었다: 먼저 13편

처음부터 에이전트 18개를 돌린 것은 아닙니다. 첫 13편은 작게 나눠 진행했고, 단계마다 브리프에 들어가야 할 내용을 하나씩 배웠습니다.

• 1편은 메인 세션 혼자 써서 형식을 정했습니다. 한국어 원문을 그 자리에서 고쳐 쓰고, 영어판과 일본어판을 새로 만드는 방식입니다.
• 3편은 메인 세션이 한 편씩 했습니다. "2021년 예제를 전부 다시 돌린다"는 원칙의 효과가 여기서 드러났습니다. 정렬 예제는 2 3 4 5 7이 아니라 23457을 출력했고, 2021년 퀵 정렬은 이미 정렬된 입력에서 스택 오버플로로 죽었습니다.
• 3편은 서브 에이전트 하나에게 맡겨, 혼자서도 형식을 지키는지 시험했습니다. 17.3분 걸렸습니다.
• 6편은 에이전트 3개가 동시에 2편씩 했습니다. 13.9분, 14.6분, 15.4분이 걸렸습니다. 여러 에이전트가 그림 폴더와 검증 도구를 같이 쓴 첫 경험이었고, 문제도 두 가지 나왔습니다. 옛 스크린샷에 Windows 계정 이름이 찍혀 있었던 것, 그리고 다른 에이전트의 그림 때문에 경고가 뜬 것입니다.

운영자가 "나머지는 하나하나 묻지 말고 전부 보강해 달라"고 했을 때 남은 글은 54편이었습니다. 무엇이든 실행하기 전에 브리프부터 썼습니다.

공통 브리프에 넣은 것

에이전트마다 주는 프롬프트는 짧게 했습니다. "이 브리프를 그대로 따를 것", 맡을 글 목록, 범위에 대한 짧은 메모가 전부입니다. 나머지는 마크다운 파일 하나에 모아 모든 에이전트가 읽게 했습니다. 이렇게 하면 프롬프트 18개가 서로 어긋나지 않고, 규칙을 고칠 때도 한 곳만 고치면 됩니다.

브리프 내용은 이렇습니다.

• 글마다 만들 것. 2021년 한국어 파일을 그 자리에서 고쳐 쓴다(slug, 원래 날짜, 워드프레스 시절 항목은 유지). 영어판과 일본어판을 만든다. 그림을 1~2개 넣는다. 줄 단위 번역이 아니라 각 언어 독자에 맞춰 쓴다.
• 핵심은 검증. 예제 코드를 모두 꺼내 C#은 .NET 10, C/C++는 clang으로 컴파일하고 실행한다. 실제 출력과 코드 번호가 붙은 실제 경고를 싣는다. 2021년의 틀린 내용은 고치고, 고쳤다고 글에 밝힌다. "C# N에서 추가"라는 주장은 낮은 언어 버전으로 컴파일해서 확인한다.
• Windows 전용 코드. WinForms와 Win32는 Mac에서 컴파일은 되지만 실행은 안 된다. 컴파일만 하고 "컴파일만 확인, 실행하지 않음"이라고 분명히 적는다. 출력을 지어내지 않는다.
• 옛 이미지. 글이 참조하는 이미지는 모두 연다. 개인정보가 찍힌 것, 낡은 것, 남의 자료에서 가져온 것으로 보이는 것은 뺀다.
• 본문 속 개인정보. 붙여 넣은 컴파일러 출력에 남은 Windows 사용자 폴더, 예제 데이터로 쓴 실명을 찾는다.
• 파일 담당 구분. 쓸 수 있는 것은 자기 content/*/<slug>.md와 data/figures/<slug>.yaml뿐이다. 다른 글, 스크립트, 템플릿, 서버는 건드리지 않는다.
• 빌드와 배포는 하지 않는다. 다른 에이전트가 병렬로 작업 중이기 때문이다.
• 보고 전에 통과할 검증 도구와 정해진 보고 형식(제목, 분량, 소제목, 그림 id, 고친 2021년 오류, 실측값, 뺀 이미지, 검증 도구의 마지막 줄).

브리프는 작업 도중에도 바뀌었습니다. 웨이브 1에서 한 에이전트는 교재에서 가져온 것으로 보이는 그림을 뺐고, 다른 에이전트는 예제 데이터에 운영자 이름이 쓰인 것을 찾았습니다. 이 두 가지 검사를 웨이브 2·3 시작 전에 브리프에 추가했기 때문에, 뒤쪽 36편은 처음부터 그 검사를 거쳤습니다.

웨이브는 이렇게 나눴다

글은 분량이 아니라 주제로 묶었습니다. 내용이 겹치는 글을 같은 에이전트에게 주기 위해서입니다.

• 웨이브 1: C# 기초 18편. 에이전트 6개가 3편씩.
• 웨이브 2: 19편. 컬렉션, LINQ 쿼리 구문과 리플렉션·파일 입출력, 레지스트리와 WinForms(이 에이전트만 4편), Win32 API 두 묶음, 정규식 입문.
• 웨이브 3: 17편. 정규식 문자 집합과 수량자 등(4편), 스택과 큐, 연결 리스트, 트리·힙·이진 탐색 트리, BFS와 DFS, 탐욕 알고리즘과 순차 탐색.

일을 고르게 나누는 것보다 주제로 묶는 것이 더 중요했습니다. 2021년 컬렉션 글 3편은 내용이 많이 겹쳐서, 한 에이전트에게 몰아 주고 "각 글의 범위를 분명히 나누고 서로 링크하라"고 지시했습니다. 관련 글을 다른 에이전트에게 나눠 줄 수밖에 없을 때는 프롬프트에 그렇게 적었습니다. 웨이브 3의 정규식 담당에게는 입문 글을 다른 에이전트가 동시에 쓰고 있으니, 반복하지 말고 링크하라고 알려 줬습니다.

웨이브 2는 웨이브 1 에이전트 3개가 아직 돌고 있을 때 시작했고, 웨이브 3은 그 4분 뒤에 시작했습니다. 그때부터 끝날 때까지 에이전트 12개가 동시에 돌았습니다. 에이전트 하나가 걸린 시간은 2편을 맡은 경우 13.1분부터, 정규식 엔진 네 가지로 4편을 시험한 경우 26.0분까지였습니다.

진행 상황은 에이전트 출력을 읽지 않고 파일 자체로 셌습니다. 한국어 파일이 legacy: false이고 영어판과 일본어판이 모두 있으면 완료로 봅니다. 이 글을 쓰면서 같은 루프를 다시 돌렸습니다(zsh).

n=0
for f in content/ko/_legacy/*.md; do
  s=$(basename $f .md)
  if grep -q "^legacy: false" $f && [ -f content/en/$s.md ] && [ -f content/ja/$s.md ]; then
    n=$((n+1))
  fi
done
echo "revised $n / $(ls content/ko/_legacy/*.md | wc -l | tr -d ' ')"

revised 67 / 67

작업 중에는 같은 루프가 한 번은 완료 38 / 67을, 10분 뒤에는 완료 64 / 67을 출력했습니다. 공유된 사실은 파일 시스템에 있고, 이렇게 세면 어떤 에이전트의 말에도 기대지 않아도 됩니다.

에이전트마다 예제를 전부 실행시킨 이유

2021년 강좌를 한 줄도 돌리지 않고 읽기 좋게 고쳐 쓰는 일은 에이전트도 할 수 있습니다. 겉보기는 멀쩡해도 내용은 틀린 채로 남습니다. 보고서를 보면 "읽어 보니 괜찮다"로는 놓쳤을 것들이 분명히 보입니다.

• C# 컬렉션 글에는 Colsole 오타가 있어 오류 CS0103이 납니다. 공개돼 있던 예제는 한 번도 컴파일되지 않는 상태였습니다.
• C++ 힙 구현은 논리 자체는 맞았습니다. 무작위 연산 40만 번의 결과가 std::priority_queue와 같았습니다. 그런데 힙 객체를 복사하면 이중 해제가 일어났고, AddressSanitizer가 이를 보고했습니다.
• Win32 예제는 한국어 창 제목으로 FindWindowA를 불렀습니다. GCC로 빌드하면 문자열이 UTF-8로 실행 파일에 들어가서, 한국어 Windows에서는 이 ANSI 호출이 절대 일치하지 않습니다.
• 2021년 예제 하나에는 닫는 중괄호 뒤에 보이지 않는 U+200B가 들어 있었습니다. 그대로 붙여 넣으면 error: '\U0000200b' does not name a type이 납니다.

모두 읽기만 해서는 안 보이고, 컴파일하면 전부 나옵니다. 그래서 브리프에서 코드 실행을 핵심 업무로, 글쓰기를 그다음으로 뒀습니다. 실제 오류 번호, 실제 출력, 무엇을 왜 고쳤는지. 검색 요약이 대신해 줄 수 없는 부분도 바로 여기입니다.

에이전트가 통과해야 한 검증 도구

보고하기 전에 에이전트는 다음을 보여 줘야 했습니다.

1. check_figures.py 오류 0건, 자기 그림에는 경고 없음. 그림을 세 언어와 휴대폰용 세로 배치로 그려 보고, 가로 1000px을 넘으면 경고합니다.
2. 한국어·일본어 그림을 실제로 그려서 눈으로 확인. qlmanage로 SVG를 PNG로 바꿔 열어 봤고, 라벨 겹침을 이렇게 찾아 고친 에이전트가 여럿이었습니다.
3. 프론트매터가 YAML로 읽히는지, 제목·설명 길이는 짧은 스크립트로 확인.
4. 자기 파일에 개인 경로나 이름이 남았는지 본문 검사.

공유 검증 도구에는 약점이 하나 있었습니다. check_figures.py는 폴더 안의 모든 그림을 그리기 때문에, 각 에이전트에게 다른 에이전트가 작업 중인 그림의 경고까지 보였습니다. 한 보고서에는 "경고 12건은 모두 다른 에이전트의 그림이고, 내 그림 6개에는 경고가 없다"고 적혀 있었습니다. 맞는 말이지만, 모든 에이전트가 출력을 담당자별로 골라내는 수고를 했습니다. 다시 한다면 검증 도구가 기본으로 지정한 slug만 보고하게 하겠습니다.

병합: 빌드 한 번, 검사 한 번, 배포 한 번

마지막 에이전트가 끝난 뒤 메인 세션 혼자 다음 순서로 병합했습니다.

1. 개인 이름과 경로 검사를 바뀐 파일만이 아니라 사이트 전체, 모든 언어에 대해 실행.
2. 어느 글에서도 참조하지 않는 옛 이미지 목록 작성.
3. 그 이미지를 로컬 백업 폴더로 이동.
4. 빌드 한 번, 콘텐츠 검사, 그림 검사.
5. --prune을 붙여 배포 드라이런을 하고, 지울 대상이 이미지뿐인지 확인.
6. 실제 배포 후 공개 주소를 골라서 확인. 지운 이미지 하나가 404를 돌려주는 것도 봤습니다.

그때 출력에서 관련 줄만 옮깁니다.

build ok → …/public  (posts: en 86, ja 86, ko 86, sitemap urls: 326)
검사: 파일 1368개, HTML 330개 → 오류 0건, 경고 0건
그림 144개 · 오류 0 · 경고 0
prune would delete: 74 | non-image: []
빌드 파일 1368개 중 변경 839개
404 /static/img/legacy/2021/06/20190404_171228_204.png
8/8 통과

바뀐 파일이 800개를 넘어서 배포에 15분 정도 걸렸습니다. 마지막에 한 번만 빌드하면 놓치기 쉬운 사고도 막을 수 있습니다. 보강 중인 글은 절대 공개되면 안 되는데, 글쓴이가 18명인 상황에서 이를 보장하는 방법은 아무에게도 배포를 맡기지 않는 것뿐입니다.

그래도 사람이 확인한 것

병렬 에이전트로 글 쓰는 시간은 줄지만, 검토 시간이 0이 되지는 않습니다. 실제로 든 검토 비용은 이렇습니다.

• 보고서 18개 읽기. 보고서마다 제목, 분량, 소제목, 고친 2021년 오류, 뺀 이미지가 적혀 있습니다. 에이전트를 넘나드는 발견은 여기서 나왔습니다. Windows 계정 이름을 언급한 첫 보고서를 보고 사이트 전체를 검색해서, 같은 경로가 남은 글 2편을 담당 에이전트가 시작하기 전에 찾았습니다.
• 지적된 이미지 뒷정리. 앞선 에이전트는 로컬 사용자 경로가 찍힌 스크린샷을 글에서 뺐지만, 파일은 서버에 그대로 있었습니다. 참조를 지운다고 파일이 지워지지는 않습니다.
• 에이전트의 자진 신고 확인. 한 에이전트는 경로를 잘못 입력해 쓸데없는 파일을 만들었다가 바로 지웠다고 보고했습니다. 그 폴더가 정말 없어졌는지 확인했습니다.
• 우리 쪽 검색 패턴 넓히기. 운영자 이름을 단어 경계로 찾던 grep이, 이름이 다른 단어에 붙은 표기를 놓쳤습니다. 본문에서 찾아낸 것은 에이전트였고, 저희는 패턴을 넓혀 전체를 다시 검색했습니다.
• 삭제 목록 읽기. prune 목록을 한 줄씩 읽었고, 이미지가 아닌 파일이 없는지도 스크립트로 확인했습니다.
• 운영자만 할 수 있는 일. 전체 실행 승인, 그리고 그 뒤 운영자에게 넘긴 두 가지입니다. 지운 이미지가 캐시에서 계속 나가지 않도록 호스팅 관리 화면에서 CDN 캐시 비우기, 새 주소의 Search Console 색인 요청(대기 183개, 하루 10개 정도).

검토에서 놓친 것도 하나 있고, 이 글을 쓰려고 다시 세다가 찾았습니다. 셸 루프 버그 때문에 안 쓰는 이미지 하나가 옮겨지지 않은 것입니다. 그 경위는 AI 에이전트의 첫 진단이 틀렸을 때에, 이미지 점검은 옛 블로그 글 개인정보·저작권 점검에 썼습니다.

병렬 에이전트가 도움이 될 때, 해가 될 때

솔직한 한계

• 가장 큰 성과는 속도가 아닙니다. 349분 분량의 작업이 약 50분에 끝난 것은 눈에 띄지만, 글의 품질은 검사의 품질만큼입니다. 컴파일과 실행이 없었다면 빨라지는 것은 틀리기까지의 시간뿐입니다.
• Windows 전용 코드는 컴파일만 했고 실행하지 않았습니다. WinForms, 레지스트리, Win32를 쓰는 글에는 그렇게 밝혔습니다. 실행 시 동작은 문서에 근거한 설명이지 저희가 잰 값이 아닙니다.
• "가져온 것 같다"는 판단입니다. 교재 그림과 비슷한 것은 뺐지만, 하나하나 출처를 증명한 것은 아닙니다. 안전한 쪽을 골랐습니다.
• 검증 도구는 확인하는 것만 확인합니다. 모든 글이 그림·콘텐츠 검사를 통과했는데도 셸 루프 버그는 빠져나갔습니다. 개수를 비교했다면 잡혔을 것이고, 지금은 점검 목록에 들어 있습니다.

다음에도 쓸 방식은 이렇습니다. 브리프를 먼저 쓰고, 에이전트마다 파일을 나누고, 모두에게 스크립트로 작업을 증명하게 하고, 빌드·배포·삭제는 한곳에 모은다.