코드베이스를 망가뜨리지 않고 여러 AI 에이전트를 사용하는 방법

AI는 제가 소프트웨어를 구축하는 방식을 완전히 바꾸어 놓았습니다.

요즘은 AI 코딩 도구를 열고, 원하는 것을 설명한 뒤, 몇 분 만에 수백 또는 수천 줄의 코드가 생성되는 것을 지켜보는 것이 매우 쉽습니다.

그리고 솔직히 말해서, 가끔은 여전히 마법처럼 느껴지기도 합니다.

하지만 프로젝트를 구축하며 AI를 집중적으로 사용한 후, 저는 한 가지를 깨달았습니다.

가장 큰 문제는 더 이상 AI가 코드를 작성하게 만드는 것이 아닙니다.

더 큰 문제는 AI가 자신이 코드를 작성하고 있는 시스템을 이해하도록 만드는 것입니다.

컨텍스트 (Context)가 없는 AI 에이전트는 위험하기 때문입니다.

그것은 오늘 어떤 기능을 만들고, 내일의 다른 세션에서는 완전히 다른 패턴을 제안할 수 있습니다. 이미 존재하는 것을 다시 만들 수도 있습니다. 애플리케이션의 나머지 부분과 일치하지 않는 새로운 구조를 도입할 수도 있습니다.

어느샌가 당신의 코드베이스 (Codebase)는 무작위적인 AI 결정들의 집합체로 서서히 변해갑니다.

그래서 저는 작업 방식을 바꿨습니다.

AI 에이전트를 마법 같은 코딩 기계처럼 취급하는 것을 그만두었습니다.

대신 그들을 제 팀에 합류하는 개발자처럼 취급하기 시작했습니다.

모든 개발자에게는 온보딩 (Onboarding)이 필요합니다

새로운 개발자를 채용한다고 상상해 보세요.

그들의 첫날에 당신은 아마 이렇게 말하지 않을 것입니다:

"여기 우리 코드베이스가 있습니다. 구축을 시작하세요."

대신 당신은 다음과 같은 것들을 설명할 것입니다:

• 제품이 무엇을 하는지
• 시스템이 어떻게 구조화되어 있는지
• 데이터베이스 설계 (Database design)
• 코딩 표준 (Coding standards)
• 내려진 중요한 결정 사항들
• 피해야 할 사항들

AI에게도 똑같은 원리가 적용됩니다.

모든 새로운 AI 세션은 프로젝트에 합류하는 새로운 개발자와 거의 같습니다.

컨텍스트 (Context)가 필요합니다.

그래서 저는 간단한 시스템을 만들었습니다.

나의 README.md는 소개서입니다

모든 진지한 프로젝트를 위해, 저는 README.md 파일을 만듭니다.

이 파일은 다음과 같은 것들을 설명합니다:

• 프로젝트가 무엇을 하는지
• 해결하려는 문제
• 주요 기능
• 설정 방법
• 프로젝트에 관한 중요한 정보

기본적으로 다음과 같습니다:

"이 프로젝트에 대해 아무것도 모른다면, 여기서부터 시작하세요."

제가 도입하는 모든 새로운 AI 에이전트는 이것을 가장 먼저 읽어야 합니다.

나의 architecture.md는 진짜 지식이 살아있는 곳입니다

이것은 아마 저에게 가장 중요한 파일일 것입니다.

나의 architecture.md 파일은 애플리케이션이 어떻게 작동하는지를 설명합니다.

다음과 같은 내용들입니다:

• 폴더 구조 (folder structure)
• 백엔드 아키텍처 (backend architecture)
• 프론트엔드 접근 방식 (frontend approach)
• 데이터베이스 구조 (database structure)
• 중요한 서비스 (important services)
• 디자인 패턴 (design patterns)
• 명명 규칙 (naming conventions)
• 서로 다른 부분들이 통신하는 방식 (how different parts communicate)

목표는 단순합니다.

저는 AI가 매번 제 아키텍처를 추측하는 것을 원하지 않습니다.

AI가 기존 구조를 이해하고 그 안에서 구축하기를 원합니다.

왜냐하면 개발자가 AI를 사용할 때 저지를 수 있는 실수 중 하나는 AI가 아키텍트 (architect)가 되도록 허용하는 것이기 때문입니다.

오늘은 AI가 하나의 패턴을 만듭니다.

내일은 다른 에이전트 (agent)가 또 다른 패턴을 만듭니다.

몇 달 후에는 아무도 시스템을 이해하지 못하게 됩니다.

AI는 제가 더 빠르게 구축할 수 있도록 도와야 하지만, 아키텍처에 대한 책임은 여전히 저에게 있어야 합니다.

더 큰 프로젝트에는 더 많은 문서화가 필요합니다

작은 프로젝트의 경우, README.md와 architecture.md만으로 충분할 수 있습니다.

하지만 더 큰 프로젝트를 위해, 저는 내용을 더 세분화합니다.

예를 들어:

docs/
    architecture.md
    database.md
...

각각의 중요한 기능은 자신만의 문서 (documentation)를 갖게 됩니다.

어떻게 작동하나요?

왜 이런 방식으로 구축되었나요?

어떤 파일들이 관여되어 있나요?

다른 개발자나 AI 에이전트가 해당 기능을 건드리기 전에 무엇을 알아야 하나요?

그러면 저의 아키텍처 문서는 모든 것을 참조하게 됩니다.

그것은 전체 시스템의 지도가 됩니다.

저는 또한 AI 에이전트에게 규칙을 부여합니다

제가 시작한 또 다른 일은 AI를 위한 규칙을 만드는 것입니다.

회사의 정책 (company policies)과 같다고 생각하면 됩니다.

제 코드베이스 (codebase)를 건드리기 전에:

• 먼저 문서를 읽을 것
• 기존 구조를 따를 것
• 이유를 설명하지 않고 새로운 패턴을 도입하지 말 것
• 승인 없이 데이터베이스 스키마 (database schemas)를 변경하지 말 것
• 주요 변경 사항 이후에는 문서를 업데이트할 것
• 아키텍처 결정 사항을 설명할 것

단순한 규칙들입니다.

하지만 이 규칙들은 많은 문제들을 방지해 줍니다.

AI 에이전트들은 작업을 완료하는 데 매우 능숙하기 때문입니다.

하지만 그들의 결정이 미칠 장기적인 영향 (long-term impact)을 이해하는 데에는 항상 능숙한 것은 아닙니다.

AI 때문에 문서화는 더욱 중요해지고 있습니다

수년 동안 개발자들은 문서를 작성하지 않는 것에 대해 농담을 주고받곤 했습니다.

"코드가 곧 문서다."

이 말은 이전에도 이미 의구심이 드는 부분이었습니다.

AI와 함께라면, 이는 훨씬 더 위험한 일이 될 것이라고 생각합니다.

여러 AI 에이전트(AI agents)가 수천 줄의 코드를 빠르게 기여할 수 있게 되면서, 문서화(documentation)는 모든 것을 연결해 주는 핵심 요소가 됩니다.

문서는 프로젝트의 기억(memory)이 됩니다.

AI는 변할 수 있습니다.

채팅 세션은 사라질 수 있습니다.

도구는 바뀔 수 있습니다.

하지만 지식은 남습니다.

개발자의 역할이 변화하고 있습니다

저는 AI가 유능한 개발자의 필요성을 없앤다고 생각하지 않습니다.

대신 무엇이 가치 있는지를 변화시킨다고 생각합니다.

코드를 작성하는 것은 점점 더 쉬워지고 있습니다.

하지만 무엇을 만들어야 하는지, 왜 만들어야 하는지, 그리고 모든 것이 어떻게 조화를 이루어야 하는지를 아는 것은 더욱 중요해지고 있습니다.

AI는 코드를 생성할 수 있습니다.

하지만 누군가는 여전히 방향을 제시해야 합니다.

누군가는 여전히 시스템을 이해해야 합니다.

누군가는 여전히 설계자(architect) 역할을 해야 합니다.

흥미로운 점은, 저 또한 이러한 문서 중 일부를 만드는 데 여전히 AI를 사용한다는 것입니다.

AI는 저의 README 파일을 초안 작성하고, 아키텍처 문서(architecture documents)를 구조화하며, 기존의 코드 흐름을 설명하고, 심지어 무엇을 문서화해야 하는지 제안하는 데 도움을 줄 수 있습니다.

하지만 중요한 것은 제가 그것을 이해하고 있어야 한다는 점입니다.

저는 그것을 검토합니다.

문서화되는 결정 사항들에 동의합니다.

왜냐하면 목표는 단순히 문서를 갖는 것이 아니기 때문입니다.

목표는 인간이든 AI든 모든 개발자가 무엇이 구축되었는지 이해하고, 모든 것을 망가뜨리지 않으면서 어떻게 계속 구축해 나갈 수 있는지 이해하는 일관된 프로젝트를 갖는 것입니다.

저에게 있어, 이것이 바로 코드베이스에 대한 통제력을 잃지 않으면서 더 빠르게 움직이기 위해 AI를 사용하는 방법입니다.