목록으로 돌아가기

AI 엔지니어링 노트

좋은 패턴도 쌓이면 리팩토링이 필요하다

2026년 3월 23일2분 읽기

AI 작업을 위해 문서를 나누는 것 자체는 낯선 일이 아닙니다. 공식 문서에서도 프로젝트 지침, 스펙, 에이전트 규칙, 작업별 문서를 분리하라고 말합니다. 저도 처음부터 AGENTS.md, spec, rules, task, lessons, SKILL 같은 층위를 나눠 쓰고 있었습니다.

문제는 분리 여부가 아니었습니다. 나눠둔 문서도 계속 쓰다 보면 쌓입니다. 좋은 규칙도 쌓이고, 임시 제약도 쌓이고, 한 번의 실패를 피하기 위한 우회도 쌓입니다. 좋은 패턴도 관리하지 않으면 레거시 코드처럼 변합니다.

문서를 나눠도 관리 문제는 남는다

처음부터 모든 것을 한 파일에 넣은 것은 아니었습니다. 프로젝트 맥락은 프로젝트 문서에 두고, 작업 상태는 task에 두고, 반복되는 패턴은 skill로 분리했습니다. claude, codex 등 공식 best practices도 참고했고, 실제로 잘 동작했던 규칙을 반영했습니다.

그런데 시간이 지나면서 다른 문제가 생겼습니다.

  • 임시 규칙이 너무 오래 남아 있음
  • 특정 태스크의 제약이 전체 규칙처럼 작동함
  • 이미 해결된 문제를 피하기 위한 우회가 계속 남아 있음
  • lessons.md에 쌓인 패턴이 정리되지 않음
  • 반복 패턴을 skill로 올릴 타이밍을 놓침
  • 전역 규칙과 프로젝트 규칙의 경계가 흐려짐

이건 문서를 몰라서 생긴 문제가 아니었습니다. 문서를 운용하면서 생기는 관리 비용에 가까웠습니다. 코드도 처음에는 잘 나뉘어 있어도 시간이 지나면 다시 정리해야 합니다. 컨텍스트 문서도 비슷했습니다.

레거시 코드를 보듯이 보게 됐다

웹 개발을 하면서 배운 기준 중 하나가 있었습니다. 처음부터 모든 utility code를 공용으로 빼지 않는 것. 한 번 쓰인 로직을 바로 shared로 올리면 과한 추상화가 됩니다. 반대로 같은 패턴이 여러 번 반복되는데도 계속 복사해서 쓰면 유지보수가 어려워집니다. 제가 배웠던 감각은 이쪽에 가까웠습니다.

- 1회성 로직은 로컬에 둔다
- 재사용이 반복되면, 패턴으로 본다
- 3회 이상 반복되면, 추상화 가능여부 와 함께 공용으로 올릴지 검토한다.

AI 작업 문서도 같은 식으로 보게 됐습니다.

한 번 나온 실패는 lessons.md에 둡니다. 반복해서 나오는 실패는 패턴으로 봅니다. 여러 태스크에서 반복되는 패턴은 SKILL.md로 올립니다. 여러 프로젝트에서 반복되는 규칙은 전역 설정 후보가 됩니다.

일회성 메모
→ task/lessons.md
  → project/SKILL.md
    → ~/.claude 공통 규칙 후보

반대로 한 번의 우회는 오래 살려두지 않습니다. 임시 규칙이 계속 남아 있으면, 나중에는 최신 작업을 방해하는 레거시 코드가 됩니다.

우선순위에 맞게 읽게 한다

컨텍스트 문서는 많이 주는 것보다 언제 읽히는지가 중요했습니다. 전역 규칙은 기본값입니다. 프로젝트 규칙은 그 위의 로컬 조건입니다. 현재 상태는 task에 있고, 반복 패턴은 skill에 있습니다. 원시 기록은 로그에 둡니다.

중요한 것은 이 구조 자체가 아닙니다. 작업할 때 실제로 어떤 순서로 읽히게 할 것인가입니다. 예를 들면 이런 흐름입니다.

CLAUDE.md에서 읽기 경로 확인
→ task/context.md로 현재 위치 확인
→ SPEC 또는 todo로 이번 작업 범위 확인
→ 필요한 경우 lessons.md 확인
→ 반복 패턴이 필요하면 SKILL.md 참조
→ 작업 후 lessons/context 정리

이 흐름이 없으면 문서는 나뉘어 있어도 다시 뭉칩니다. 모델은 많은 문서를 가진 것이 아니라, 지금 어떤 문서를 봐야 하는지 알아야 합니다.

좋은 컨텍스트도 청소가 필요하다

이 글에서 말하고 싶은 것은 문서를 나누자는 이야기가 아닙니다. 이미 나누고 있어도 계속 정리해야 한다는 쪽에 가깝습니다.

좋은 규칙은 추가됩니다. 좋은 패턴도 추가됩니다. 실패를 줄이기 위한 우회도 추가됩니다. 그런데 시간이 지나면 그중 일부는 제거되어야 하고, 일부는 승격되어야 하고, 일부는 더 좁은 위치로 내려가야 합니다.

좋은 코드도 관리하지 않으면 레거시 코드가 됩니다. 좋은 컨텍스트도 마찬가지였습니다. 개발자에게 코드 관리 와 문서 관리의 이중화는 정말 힘든일에 속합니다. 하지만 이제 구현을 ai 에게 위임 할수록 컨텍스트도 주기적으로 리팩토링해야 한다고 생각하고 실천하려고 합니다.