AI를 잘 쓰기 위해 시도했던 경험과 실패 회고

AI와 함께 일하며 느낀 AI(Claude) 잘 쓰는 법을 쓴 지 7개월이 지났습니다. 그 사이에도 회사에서는 AI를 계속해서 최대한 활용하는 방향으로 개발이 진행되었고, 저 역시 이것저것 시도하며 AI를 잘 쓰기 위해 노력하였습니다. 그 과정에서 확실히 이 방법은 AI를 사용하는데 도움이 되었다 라는 것도 있었고, 문제를 해결해주지 못한다거나 오히려 문제를 일으킬 수 있는 방식도 있었습니다. 이번 포스팅에서는 이 경험들을 공유하며 AI 시대 개발자로서 나아가는 과정을 기록하려 합니다.

AI를 사용하면서 느끼는 것

저는 반복되는 굴레속에 행복을 찾아야 한다는 점에서, 시지프스의 형벌을 인생에 비유하는 것을 꽤나 좋아하는데요. 개발이라는 업무 자체도 시지프스의 형벌과 어느정도 닮아있다고 생각합니다. 그런 면에서 AI를 사용하면서 느낀 점을 비유하자면, 마치 기계를 타고 설산에서 바위를 밀어올리는 것 같다고 생각했습니다. 힘들게 밀어 올리진 않아도 되지만, 바위가 미끄러지지 않게 조심조심하며 올려야 합니다. 눈덩이가 너무 불어나지 않게 중간중간 바위를 털어주기도 해야합니다.

AI가 통일성 있는 개발을 하도록 만들기 위한 노력

AI를 사용해서 개발하다보면 기존 공통컴포넌트를 사용하지 않거나, 갑자기 기존 컨벤션을 지키지 않고 새로운 방식으로 개발을 할 때가 있습니다. 이를 보완하기 위해서 가이드라인을 세부적으로 지칭하거나, 에이전트나 스킬을 활용해서 보완하려고 했습니다.

디자인 시스템 에이전트 활용

그중 가장 효과적이었던 것은 에이전트를 활용한 개발이었습니다. 새로운 관리자페이지를 만들 때, 기존 디자인 시스템과 레이아웃을 지키며 개발하는지 감시하는 에이전트가 추가되었습니다. 이미 만들어진 페이지들의 레퍼런스를 바탕으로, 기존 컴포넌트와 토큰만을 사용하도록 강제하고 임의로 새로운 속성이나 기능을 추가하지 못하도록 합니다. 한번 실행되면 20~30분 정도의 시간이 소요되긴 했지만, 30분만에 페이지 하나라고 생각하면 엄청난 효율성을 보여주는 방식이었습니다.

문제는 새롭게 페이지를 만드는 것이 아니라, 디자인을 수정할 때에도 20분이 걸린다는 점이 문제였습니다. 때문에 새로운 페이지를 개발할 때 필요한 세부적인 UI는 개발자의 손에서 이뤄졌고, 동일한 성격의 페이지를 만든다거나, 마이그레이션 등의 케이스 외에는 해당 에이전트를 지양하게 되었습니다.

이는 제가 관심을 갖고 있는 오픈소스인 wafflebase에서도 갖고 있는 문제인데, AI를 적극적으로 활용하는 오픈소스인 wafflebase는 체계적인 하네스를 바탕으로 AI로 인한 문제를 방지하고 있습니다. 또한 같은 문제를 각각 해결하게 한 뒤, 두 해결방식이 일치하는지를 검토하여 예외적인 문제가 없는지 검토하는 등의 방식을 통해서 AI의 저점을 높이려는 시도에도 적극적입니다. 다만, 이로 인해서 간단한 개발에서도 AI를 사용하면 30분 이상의 시간이 소요된다는 점에서 오히려 AI를 지양하게 되었습니다.

Claude.md 컨텍스트 한계 극복을 위한 인덱싱

Claude.md를 포함한 개발지침을 활용한 방식은, AI 개발에서 가장 흔하고 많이 사용하는 방식이 아닐까 싶습니다. 별도로 스크립트를 작성하지 않더라도 특정 지침을 지키도록 만들어진 Claude.md는, 매 세션마다 선언되어야 하기 때문에 용량의 한계가 있다는 점이 있습니다.

저희 팀에서는 이를 극복하기 위해 작업의 성격이나, 위치 등으로 구역을 나눠 문서를 분산시키고 개발 중 필요한 지침이나 히스토리를 AI가 알아서 읽을 수 있도록 개발하였습니다. Claude.md는 인덱스 역할을 하며 개발에 필요한 문서를 읽을 수 있도록 안내하고, 새로운 개발이나 수정을 할 때면 문서를 생성하여 다른 세션에서도 동일한 컨텍스트를 유지할 수 있게끔 설계했습니다. 인덱스는 확실히 효과가 있었습니다. 모듈 진입 속도가 눈에 띄게 빨라졌고, 히스토리도 유지될 수 있었습니다. 그리고 개발 중에 만들어낸 문서가 500개가 쌓일 때 까지는 이 방식의 문제를 알지 못했습니다.

개발이 진행되면서 눈치채지 못하게 문서는 계속해서 쌓이고 있었고, docs 폴더 내의 md 파일은 500개를 넘어가고 있었고, 이에 따라서 인덱스 역할을 하던 Claude.md도 계속해서 눈덩이처럼 불어나고 있었습니다.

문제점을 보완하기 위한 방식과 방식의 문제점을 보완하기 위한 방식

AI를 적극적으로 활용하고 있는 오픈소스들은 어떻게 이런 문제들을 해결하는지 찾아보았습니다. 그 중 페이스북의 Astryx 역시 AI가 문서를 생성하게끔 하지만, 낡은 문서를 관리함으로써 계속해서 문서가 늘어나지 않고 관리되고 있었습니다. 낡은 문서를 판단하는 방식은 문서 내의 참조가 살아있는지를 기계적으로 판단해서 업데이트하거나 삭제하도록 하여, 꼭 필요한 문서만을 남기게 됩니다. 역시 페이스북 이구나 싶은 아이디어 였지만, 회사에 이 방식을 도입했을 때 삭제할 수 있는 문서는 고작 열 몇개 뿐이라는 응답을 받았습니다.

AI로도 극복할 수 없는 구조적 한계

그 이유는 히스토리 때문이었습니다. 현 회사의 프론트엔드팀은 개발 히스토리를 따로 관리하고 있지 않습니다. 그렇기에 개인적으로 노션을 업데이트하면서 혼자만이라도 문서화를 해나가고 있었습니다. 커밋 역시 'wip, .' 으로 대충 작성하는 것이 대부분이었지만 최근 AI가 작성해주는 커밋메시지 덕분에 그나마 커밋히스토리가 유지될 수 있었습니다. 히스토리의 부재로 인해 발생하는 문제를 팀에서도 어느정도 인식하고 있기 때문에 이를 주석으로 남기기 위한 AI 지침들도 존재하고 있습니다. 이로인해 작성되는 기나긴 주석 때문에 실제로 코드를 읽을 때 꽤나 높은 피로감으로 작용하기도 하고, 파일의 line수가 비약적으로 늘어나는 문제가 있었습니다.

그렇기 때문에 저는 히스토리 때문에 문서를 코드베이스에 계속 유지해야 한다면, '히스토리를 아예 커밋메시지로 이관하자' 라는 생각도 해보았습니다. 하지만 이 역시 commit 이 쌓일수록 눈덩이처럼 불어날 수 밖에 없는 구조였고, 그마저도 모두가 AI Skill을 사용해서 커밋을 해야만 지켜지는 방식이었습니다. 여기서 저는 AI로도 극복할 수 없는 문서화의 한계와 아쉬움을 느끼게 되었습니다.

ㅤ

길가에 핀 꽃을 알아볼 때까지

토큰과 퀄리티의 트레이드오프는 지금도 겪고 있고, AI가 구조적인 문제까지 풀어주는 은탄환이 되지는 못했습니다. 눈덩이가 불어나지 않는 완벽한 구조는 아마 앞으로도 못 만들 것 같습니다. 다만 그래도 AI는 계속 발전하고 있습니다. 컨텍스트 양은 비약적으로 늘고 있고, 컨텍스트 최적화를 고민하던 게 무색해질 만큼 모델이 좋아지고 있습니다. 지금처럼 여러 방안을 찾고 적용하면서 불어난 눈을 털어내고, 산에 등산로를 내듯 개발 문화와 구조를 개척해나가다 보면, 언젠가는 바위를 올리는 길에서 길가에 핀 꽃을 알아볼 여유도 생기지 않을까요?