Insights
AI가 자동으로 큐레이션·번역·정리하는 기술 동향 피드입니다.
AI 코딩 에이전트에게 구현을 맡길 때, 계획 단계의 모호함으로 인해 독창적이고 비표준적인 코드가 생성되어 기술 부채가 쌓일 수 있습니다. 이를 방지하려면, 구현 전에 논리적으로 깊게 탐색하는 계획 단계를 설정하고 미결정 항목을 명확히 결정해야 합니다.
AI 자동 생성 콘텐츠
본 콘텐츠는 Zenn AI의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기Claude Code와 같은 코딩 에이전트에게 구현을 맡기고 있으면, 기존의 공통 함수를 사용하지 않고 유사한 함수를 새로 만들거나, 다른 부분과는 다른 방식으로 오류 처리를 하기도 합니다.
이러한 원인 대부분은 구현 전 계획의 모호함에 있습니다. 계획에 미결정 또는 검토가 필요한 항목이 남아 있으면, 에이전트는 구현하는 과정에서 이들 부분을 스스로 판단하여 구현합니다. 이때 사용되는 재료는 구현을 위해 읽고 있는 좁은 컨텍스트 범위 내의 정보뿐입니다. 결과적으로 해당 구현 부분에서는 작동하지만, 코드 전체와는 맞지 않는 독창적인 구현이 발명됩니다. 특히 최근 LLM은 성능이 높아진 만큼, 오히려 독창성이 발휘되기 쉽습니다.
이러한 현상이 쌓이면 결국 기술 부채가 됩니다.
이 기술 부채를 줄이기 위해서는, 구현 전에 계획 단계를 설정하고 그 계획에서 폭넓고 깊게 탐색 및 계획하도록 하는 것이 중요합니다. 이를 위해서는 다음 두 가지 사항에 더 신경 써야 합니다.
본 기사에서는 위 두 가지 사항을 구체적으로 실천하는 포인트와 마지막으로 CLAUDE.md의 예시문을 제공합니다.
1. 관련 코드를 읽는다
2. 일반적인 방식을 조사한다
3. 테스트하여 확인한다
...
경험자라면 알겠지만, 코딩 에이전트는 계획을 작성할 때 놀라울 정도로 실제 코드를 많이 읽지 않습니다. 프로젝트 폴더에 있는 관련 문서나 grep으로 '대충 읽어' 구현 부분을 파악합니다. 그리고 구현 시가 되어서야 하나하나 코드를 읽기 시작하며 계획과 구현의 차이를 발견하면, 그 자리에서의 판단으로 구현 방식을 변경하고 결과적으로 독창적인 구현이 생겨납니다.
따라서 구현 계획에는 코드의 해당 부분을 읽고 확인한 내용만 작성하도록 해야 합니다. 또한, 코드 읽는 방법으로는 다음 지시도 하고 있습니다.
일반적인 구현은 그 문제에 대해 간결하고 정확한 경우가 많습니다. 따라서 계획 작성 시, 먼저 주류 도구나 라이브러리가 해당 문제를 어떻게 해결했는지 공식 문서나 레포지토리에서 조사하도록 합니다.
AI 에이전트는 Websearch나 Webfetch를 피하는 경향이 있으므로, 이것 역시 명확하게 지시하지 않으면 조사하지 않습니다. 절차에 기재하여 바퀴 재발명(reinventing the wheel)을 하지 않도록 해야 합니다.
라이브러리나 API, 커맨드의 동작 방식(응답 내용이나 소요 시간 등)은 문서나 코드를 읽는 것만으로는 알 수 없는 경우가 있습니다. 하지만 이 부분을 방치하면 AI 에이전트는 추측으로 계획을 쓰거나 미결정 사항으로 구현 시의 숙제에 넘깁니다. 이는 결과적으로 구현 중에 그 자리에서 생각하여 기술 부채가 됩니다.
따라서 테스트를 할 수 있다는 허가를 명시적으로 개발 규칙에 포함하고 있습니다.
사전에, 구현으로 인해 영향을 받는 파일/호출원(caller)/설정 키/폴백을 조사하고 구체적으로 file:line과 함께 기재하도록 합니다. 이를 통해 계획 검토의 포괄성을 높일 수 있습니다. 또한, 파일과 라인까지 작성하게 함으로써 AI 에이전트가 실제로 코드를 읽었다는 증명 역할도 하게 됩니다. 아울러, 앞으로 작성할 처리와 동일한 것이 이미 없는지 조사하도록 합니다.
계획서 필수 항목은 체크리스트 2에 있습니다. 또한, '별도 세션의 Claude가 받아들여 실행할 수 있는 수준의 상세함'으로 작성하도록 지시합니다. 이렇게 함으로써 계획의 모호성이나 누락을 없애도록 합니다.
중복성 제거와 유지보성 고려도 규칙으로 지시하고 있습니다. 구체적으로는, 코드 변경은 임계점(여러 처리의 근본/집약된 부분)에서 실행하도록 검토하게 합니다. 그 결과, 하나의 변경에 대해 분기되는 여러 곳의 코드를 수정하는 일이 없도록 합니다.
또한, '하지 않을 것'도 지정합니다. 요청하지 않은 기능 추가나, 곁다리 리팩터링, 과도한 범용화는 하지 않도록 하고 있습니다.
AI 에이전트가 작성하는 계획서는 부주의할 경우, 상당한 미결정 내용이 혼입되는 경우가 많습니다(솔직히 말하자면). 이들 역시 구현 중에 AI 에이전트가 그 자리에서 판단하여 채워버립니다. 따라서 '검토 필요', 'TBD' 내용은 계획 제시 전까지 모두 해소시킵니다. 방법은 두 가지입니다.
작성된 계획서는 리뷰 에이전트를 세워 검토 → 수정하게 합니다. 에이전트에게 지시하는 검토 관점은 체크리스트 4와 같습니다.
구현은 사용자의 승인을 받은 후에 실행합니다. 게다가, 구현 중에 방식이나 결정 사항이 바뀌면 그 시점에서 다시 승인을 받게 하여 독자적인 판단이 혼입되지 않도록 합니다.
file:line## 계획 작성 방법
계획은, 구현 중에 그 자리의 판단이 필요 없는 상태까지 채워서 제시한다.
### 절차
...
구현 중의 판단을 막기 위해,
AI 에이전트의 구현을 보면, 예정을 변경해서 터무니없는 구현을 한다고 중얼거리기 시작했다. 그런 일이 없도록, 사전에 계획을 확실히 실행합시다!!
