에이전트가 읽을 저장소

에이전트와 일하는 프런트엔드 #1 — 주석 207개를 지우고, 문서 12종을 1종으로 합치고, 규칙을 파일에 박기까지. 저장소를 에이전트가 읽을 수 있게 만든 한 주의 기록이에요.

안녕하세요. 임상시험 시스템을 만드는 Frontend Developer 민은영입니다. 앞으로 네 편에 걸쳐 에이전트와 일하면서 바뀐 것들을 정리해 보려고 하는데요. 첫 편은 코드를 짜기 전에 저장소부터 손봐야 했던 이야기예요.

에이전트에게 일을 시키다 보면 이상한 순간이 옵니다. 같은 요청인데 어떤 날은 정확하게 고치고, 어떤 날은 3개월 전에 폐기한 방식으로 되돌려 놓아요. 처음에는 모델 탓을 했습니다. 몇 번 반복되고 나서야 원인이 다른 데 있다는 걸 알았어요. 저장소가 에이전트에게 거짓말을 하고 있었거든요.

사람은 저장소의 거짓말에 면역이 있죠. 주석에 적힌 날짜가 낡았다는 걸 알고, 플랜 문서가 세 개면 슬랙에서 최신본을 물어보고, // 임시라고 쓰인 코드가 2년째 프로덕션에 있다는 것도 알고요. 에이전트는 그 면역이 없습니다. 읽은 대로 믿어요.

그래서 한 주를 코드가 아니라 저장소를 읽히게 만드는 데 썼습니다. 이 글은 그때 지운 것과 남긴 것에 대한 기록이에요.

1. 주석은 코드보다 빨리 썩어요

가장 먼저 손댄 건 주석이었는데요. 프로덕션 코드의 주석을 전수로 읽고 분류했더니 이렇게 나왔어요.

종류	건수	예
묘비 (tombstone)	6	이미 지운 함수가 "여기 있었다"고 알려주는 주석
이력 조각	18	"2024-11 A방식 → 2025-03 B방식으로 변경"
동어반복	183	// 사용자 이름을 반환한다 바로 아래 return user.name

합쳐서 207건이에요. 압도적으로 많은 건 동어반복이었고요. 여기에 주석 안에 박혀 있던 날짜 44건(28개 파일)을 더 걷어냈습니다. 프로덕션 주석이 2,202줄에서 2,092줄로 줄었어요.

세 종류 다 사람에게는 무해합니다. 그냥 눈이 안 가니까요. 에이전트에게는 셋 다 유해해요. 묘비는 없는 함수를 있다고 알려주고, 이력 조각은 폐기된 방식을 현행처럼 읽히게 하고, 동어반복은 컨텍스트 창을 먹으면서 아무 정보도 주지 않습니다.

지우는 것보다 중요한 건 다시 쌓이지 않게 하는 것이었어요. 그래서 규칙 하나를 문서에 박았습니다.

결정의 시점과 경위는 커밋 로그와 이슈에서 본다. 주석에는 쓰지 않는다.

이력을 주석에 적고 싶어지는 이유는 대개 "나중에 왜 이렇게 했는지 기억 안 날까 봐"죠. 그런데 그 정보는 이미 커밋과 이슈에 있어요. 주석에 복사해 두면 원본이 바뀔 때 사본만 낡습니다. 사본을 지우는 게 아니라 사본을 만들지 않는 것이 규칙이어야 해요.

2. 정본이 여러 개면 최신본은 선택되지 않아요

다음은 문서였는데요. 기능별로 흩어져 있던 플랜·잔여 작업 문서가 12종이었고, 그중 6묶음이 서로 내용이 겹쳤어요. 겹친 것들끼리도 미묘하게 달랐고요. 어떤 문서는 이미 끝난 항목을 미완으로 두고 있었고, 어떤 문서는 폐기한 방식을 그대로 남겨 뒀습니다.

사람이 이 상태를 견딜 수 있는 건 "아 그건 옛날 거예요"라고 말해 줄 동료가 있기 때문이에요. 에이전트에게는 그 동료가 없습니다. 12종을 전부 읽고 모순되는 지시를 동시에 따르려고 해요. 결과물이 이상해지는 건 당연하죠.

중복을 제거하고 하나의 정본 파일로 합쳤습니다. 그 과정에서 "이미 끝났는데 문서에만 남아 있던 항목" 11건이 정리됐어요. 문서를 합친 게 아니라 사실을 한 곳에 모은 것에 가깝습니다.

정본을 하나로 만들 때 지킨 것 하나 — 합친 뒤 옛 문서를 남겨 두지 않았어요. "혹시 몰라서" 남긴 파일이 다음 달에 다시 정본 행세를 하거든요.

3. 참조 번호가 어디를 가리키는지 아무도 몰라요

협업이 오래되면 코드 주석에 사내 참조 번호가 박히기 시작하죠. 우리 저장소에도 네 종류가 섞여 있었어요. 어떤 건 디자인 판정 번호, 어떤 건 시안 번호, 어떤 건 백엔드 조사 문서의 절 번호였습니다.

문제는 그 번호들이 어느 문서의 무엇인지 아는 사람이 저 하나였다는 거예요. 새로 온 사람도 못 찾고, 에이전트는 더 못 찾습니다. 번호만 보고 지레짐작해서 엉뚱한 결론을 내요.

그래서 색인 문서를 하나 만들었어요. 번호 체계마다 "이건 무엇이고, 원문은 어디에 있고, 형식은 이렇다"를 적은 한 장짜리 표입니다. 만드는 데 반나절 걸렸고, 그 뒤로 "이 번호 뭐예요?"라는 질문이 사라졌어요.

부수 효과가 하나 있었는데요. 색인을 만들면서 더 이상 존재하지 않는 요구사항을 가리키는 주석 89줄이 드러났습니다. 색인은 그 자체로 죽은 참조를 찾는 도구였어요.

4. 규칙은 리뷰가 아니라 파일에 둡니다

위 세 가지를 정리하고 나서, 정리한 내용이 유지되게 만들 자리가 필요했어요. 저장소 루트의 에이전트 규칙 파일(AGENTS.md)에 다음을 명문화했습니다.

• 주석 규칙 — 결정 시점은 커밋 로그와 이슈에서 본다
• 폴더 규약 — 훅과 스토어는 model, 순수 함수는 lib. 예외 경로도 함께 명시
• UI 텍스트 표기 규칙 — 대소문자 기준, 단복수 처리, 목록 단위 명사

여기서 배운 게 하나 있어요. 예외를 같이 적지 않으면 규칙은 지켜지지 않습니다. "훅은 model에"만 적으면 쇼케이스 라우트처럼 규칙 밖에 있어야 하는 디렉터리에서 에이전트가 규칙을 억지로 적용해요. 예외를 명시한 뒤로 그 실수가 없어졌습니다.

규칙을 파일에 두는 것의 진짜 이점은 에이전트가 아니라 리뷰에서 나와요. 같은 지적을 세 번 하고 있다는 걸 깨달으면, 네 번째부터는 지적 대신 규칙 한 줄을 추가하면 되거든요. 리뷰는 사람 수에 비례해 실패하지만 파일은 그렇지 않습니다.

물론 규칙 파일이 만능은 아니에요. 길어지면 그 자체가 컨텍스트를 먹고, 에이전트가 앞쪽만 보는 일이 생깁니다. 저도 아직 적정 길이는 못 찾았어요. 지금은 리뷰에서 두 번 이상 나온 말만 올리는 기준으로 버티고 있습니다.

5. 그래서 무엇이 달라졌나

정직하게 말하면, "에이전트 정확도가 몇 % 올랐다" 같은 숫자는 없어요. 그런 걸 재려면 통제된 비교가 필요한데 실무에서는 불가능했거든요.

대신 관찰한 것들은 이렇습니다.

• 폐기된 방식으로 되돌아가는 일이 사라졌어요. 원인이 이력 주석과 중복 문서였다는 게 사후에 분명해졌고요.
• 컨텍스트에 넣을 파일을 고르는 시간이 줄었어요. 정본이 하나면 고를 게 없으니까요.
• 온보딩 질문이 줄었어요. 색인과 "첫날 읽을 순서"를 넣은 뒤 사람에게서도 같은 효과가 났습니다.

마지막 항목이 이 작업의 진짜 성격을 말해 줘요. 저는 에이전트를 위해 저장소를 정리했다고 생각했는데, 결과물은 사람이 읽기에도 더 나은 저장소였습니다. 에이전트는 우리 문서가 실제로 얼마나 엉망인지를 아프게 드러내는 센서에 가까웠어요.

시작한다면 순서는 이렇게

하루 안에 할 수 있는 것부터 적어 볼게요.

1. 동어반복 주석부터 지웁니다. 가장 많고, 지워도 아무도 다치지 않아요. 리스크 0의 워밍업이죠.
2. 중복 문서를 찾습니다. 같은 주제 파일이 두 개 이상이면 하나로 합치고 나머지는 지워요. 남기지 않습니다.
3. 규칙 파일을 만듭니다. 처음부터 완성할 필요 없어요. 리뷰에서 두 번 이상 한 말을 한 줄씩 옮기면 됩니다.
4. 예외를 같이 적습니다. 규칙보다 예외가 규칙을 살려요.

주석 하나 지우는 건 커밋 한 줄이지만, 207개를 지우는 건 결정이에요. 이 결정은 스프린트 중간에 곁다리로 못 합니다. 저는 실기능이 일단락된 주를 통째로 여기에 썼고, 그 판단이 이 작업에서 제일 잘한 부분이었다고 생각해요.

적용해보기

저장소를 열어 두고 이 질문들을 던져보면 좋겠어요.

• 같은 주제를 다루는 문서가 두 개 이상 있나요? 그중 어느 게 정본인지 파일만 보고 알 수 있나요?
• 주석에 적힌 날짜 중 올해 것이 몇 개인가요?
• 코드에 박힌 사내 참조 번호를 해석할 수 있는 사람이 몇 명인가요?
• 리뷰에서 세 번 이상 반복한 지적이 있다면, 그건 지금 어디에 적혀 있나요?

다음 편에서는 이렇게 정리한 저장소에 에이전트가 코드를 쓰기 시작했을 때, 그 코드의 책임을 누가 지는지를 써볼게요. 읽어주셔서 감사합니다.

---

이 글은 특정 제품·조직의 세부를 뺀 일반화된 기록입니다. 수치는 실제 작업분이고, 사례는 제 환경에서의 관찰이에요.