조금 쓸 내용을 정리하다 보니 읽을거리가 엄청나게 길어져서, 몇 번에 나누어 게시하겠습니다.

일단 각 기사에는 전체 링크도 준비해 둘 테니, 순서대로 읽어주시면 감사하겠습니다.

AI에게 적절한 프레임워크를 생각해 보았는데,

결국, 인간용 아키텍처와 AI용 아키텍처는 별개의 것으로 생각해야 하는 시대가 오는 걸까?

라는 점을 나름대로 정리해 보았습니다!!

지금까지 AI와 논의해 온 내용을 되돌아보니, 다음과 같은 키워드가 나왔습니다.

• Feature 단위로 컨텍스트 (Context)를 작게 만들기
• DRY는 '쓰는 비용'뿐만 아니라 '읽는 비용'도 고려하기
• Markdown을 사양서가 아닌 지식 베이스 (Knowledge Base)로 다루기
• Framework는 AI가 헤매지 않을 입구를 제공하기

여기까지 오면 자연스럽게 한 가지 의문이 생깁니다.

🤔 에스케 씨

"그럼, 이 모든 것을 도입하면 어떤 아키텍처가 되나요?"

AI는 잠시 생각한 뒤, 이렇게 대답했습니다.

🤖 AI

"아직 베스트 프랙티스 (Best Practice)라고 할 수는 없지만, 현시점이라면 이러한 구성을 제안합니다."

project/
├── README.md
├── CLAUDE.md
...

언뜻 보기에는 그리 특별한 구성으로 보이지 않습니다.

하지만 AI가 설명해 준 것은 **폴더 구성 그 자체가 아니라, '각각의 역할'**이었습니다.

먼저 features입니다.

🤔 에스케 씨

"Feature First는 지금까지와 같은 생각 아닌가요?"

🤖 AI

"비슷하지만, 목적이 조금 다릅니다."

인간은 책임을 분리하기 위해 Feature를 만듭니다.

반면 AI는,

한 번에 읽는 범위를 작게 만들기 위해

Feature를 이용합니다.

예를 들어,

"주문 목록 화면을 수정해 주세요."

라는 의뢰라면,

AI가 가장 먼저 읽는 것은

features/order

뿐입니다.

그곳에서 완결될 수 있다면, 다른 Feature를 읽을 필요가 없습니다.

즉,

Feature = AI의 컨텍스트 (Context)를 가두는 단위

라는 생각이 됩니다.

다음은 shared입니다.

솔직히 이 부분이 가장 의외였습니다.

🤔 에스케 씨

"shared는 공통 처리를 두는 곳 아닌가요?"

🤖 AI

"'공통이니까'가 아니라, '변경 이유가 공통이니까' 둡니다."

이 말은 상당히 인상에 남았습니다.

예를 들어,

shared/database

여기에는 데이터베이스에 관한 정의를 둡니다.

이유는 간단합니다.

DB 스키마 (Schema)가 바뀌면, 주문 기능뿐만 아니라 로그인 기능이나 프로필 기능에도 영향을 미칩니다.

즉,

DB 변경

이라는 동일한 이유로 수정되기 때문입니다.

반대로, 주문 화면 전용 로직을 shared에 넣어버리면, AI는 매번 shared를 읽게 됩니다.

그렇게 되면 컨텍스트 (Context)가 넓어져 버립니다.

다음은 framework입니다.

이곳은 인간을 위한 것이라기보다, AI와의 약속이 됩니다.

AI가 이용하는 것은,

Utilities.moneyFormat()
Utilities.warekiConvert()
Utilities.phoneFormat()

뿐입니다.

내부적으로

money.dart
wareki.dart
phone.dart

로 나누어져 있어도 AI는 신경 쓰지 않습니다.

중요한 것은,

AI가 망설임 없이 사용할 수 있는 입구가 하나라는 것.

이 생각은 이용자용 API를 설계하는 감각과 비슷할지도 모릅니다.

이어서 framework/docs입니다.

처음에는 README를 충실히 작성하면 된다고 생각했습니다.

하지만 AI는 달랐습니다.

🤖 AI

"거대한 README보다, 작은 지식을 따라가는 편이 이해하기 쉽습니다."

예를 들어,

README
↓
format/
...

라는 흐름입니다.

money.md에 쓰는 내용은,

• 무엇을 하는 함수인지
• 인수 (Argument)
• 반환값 (Return Value)
• 샘플 코드
• 사용하지 않는 케이스

정도로 충분합니다.

AI는 필요한 지식만 읽을 수 있으면 구현할 수 있습니다.

여기서 드디어 CLAUDE.md의 역할이 보이기 시작했습니다.

인간이라면 경험을 바탕으로 "이쯤을 보면 있을 것 같다"라고 찾을 수 있습니다.

하지만 AI는 명확한 규칙이 있는 편이 헤매지 않습니다.

예를 들어,

1. README.md를 읽는다
2. framework/docs를 읽는다
3. 대상 Feature를 읽는다
   ...

라는 순서를 적어두는 것.

단지 이것만으로도,

AI가 매번 다른 방식으로 찾는 것을 방지할 수 있을지도 모릅니다.

지금까지 이야기를 들으면서,

제 안에서 하나의 문장으로 정리되었습니다.

그것은 바로,

AI가 헤매지 않는 설계

입니다.

예를 들어,

날짜를 포맷팅(Formatting)하고 싶다고 가정해 봅시다.

그때,

DateUtil?
DateFormatter?
FormatUtil?
...

라고 AI가 고민하기 시작한다면,

그 시점에서 불필요한 토큰(Token)과 시간도 소비하게 됩니다.

하지만,

Utilities.dateFormat()

밖에 존재하지 않는다면,

헤맬 여지가 없습니다.

이는 사람도 마찬가지입니다.

신입 사원이 합류했을 때,

"날짜 포맷팅은 어디에 있나요?"

라는 질문이 줄어들지도 모릅니다.

즉,

AI를 위해 생각한 설계가 인간에게도 이해하기 쉬운 설계가 될 가능성이 있습니다.

여기까지 읽으면서,

이런 의문을 가진 분도 계실 것입니다.

• Utilities가 거대해지지는 않을까?
• Markdown의 관리 비용은?
• AI는 정말로 Markdown을 읽어줄까?
• 에이전트(Agent)가 바뀌어도 같은 설계로 괜찮을까?

사실, 이 부분에 대해서는 저 자신도 답을 가지고 있지 않습니다.

AI에게 물어봐도,

🤖 AI

"현시점에서는 케이스 바이 케이스(Case by case)입니다."

라는 답변이 돌아왔습니다 (웃음).

결국,

아직 아무도 대규모 실적을 쌓아 올리지 못한 영역인 것 같습니다.

그렇기에,

이 아키텍처(Architecture)는 완성형이 아닙니다.

「AI 네이티브 아키텍처 Ver0.1」

라는, 현시점에서의 가설입니다.

어쩌면 몇 년 후에는 완전히 다른 형태가 되어 있을지도 모르고,

도중에 생각하는 것이 지겨워져서 AI가 마음대로 만들게 하고 있는 미래밖에 보이지 않습니다.

하지만 AI가 개발의 중심에 가까워지고 있는 지금, 이러한 설계 사상(Design Philosophy)에 대해 고민하기 시작하는 것 자체에는 가치가 있지 않을까요.

그리고 마지막으로, 이 시리즈 전체를 통해 인간인 에스케(え～すけ) 씨가 느낀 점을 정리해 보고자 합니다.