안녕하세요 여러분, dev.to에 올리는 저의 첫 게시물이며, 제가 구축해 온 프로젝트를 공유하고자 합니다.

• Cursor 및 Claude Code를 사용하며 계속 마주쳤던 문제는 다음과 같습니다: AI가 코드베이스에서 왜 특정 결정이 내려졌는지 전혀 모른다는 점입니다.
• AI는 기존 아키텍처(Architecture)를 깨뜨리는 리팩터링(Refactor)을 제안합니다. 이미 검토하고 거절했던 라이브러리를 추천하기도 합니다.
• 저의 제약 사항을 알지 못합니다. 결국 매번 새로운 채팅 세션마다 동일한 컨텍스트를 다시 설명해야 했고, 새로운 개발자가 프로젝트에 합류하면 그들의 AI 역시 다시 처음부터 시작해야 합니다.

저는 이를 해결하기 위해 Archie를 만들었습니다. 단 한 번의 명령으로 가능합니다:

npx archie init

이 도구는 코드베이스와 git 히스토리를 읽고, Gemini를 사용하여 구조화된 ARCHITECTURE.md를 생성하며, git post-commit hook을 통해 해당 문서를 자동으로 업데이트된 상태로 유지합니다. 수동 관리가 필요 없습니다.

이 문서는 다음 내용을 포착합니다:

• 프로젝트가 실제로 수행하는 작업
• 각 기술이 선택된 이유
• 실제 파일을 통해 추적된 핵심 흐름(Core flows)의 작동 방식
• 주요 결정 사항 및 거절된 대안들(그리고 그 이유)
• 알려진 제한 사항

결과적으로 프로젝트를 여는 모든 개발자와 모든 AI 도구는 원래 개발자가 가졌던 것과 동일한 컨텍스트를 얻게 됩니다. AI는 당신이 이미 배제한 사항들을 다시 제안하는 것을 멈추게 됩니다.

논의할 가치가 있는 기술적 결정들

컨텍스트 윈도우 (Context window)
거대한 컨텍스트 윈도우를 활용하기 위해 특별히 Gemini를 선택했습니다.

증분 업데이트 (Incremental updates)
Archie는 정적 임포트 분석(Static import analysis)을 통해 의존성 그래프(Dependency graph)를 구축합니다. 파일이 변경되면, 해당 파일의 직접적인 임포트 대상과 임포터(즉, 이웃 파일들)를 찾아내어 코드베이스 전체가 아닌 해당 부분만 Gemini에 전송합니다. 이를 통해 커밋당 업데이트 속도를 빠르게 유지하고 비용을 저렴하게 유지합니다.

상태 관리 (State management)
.git/archie/state.json이 lastProcessedCommit을 추적합니다. 훅(Hook)은 마지막으로 처리된 커밋과 HEAD 사이의 모든 커밋을 가져오며, 단순히 최신 커밋만 가져오는 것이 아닙니다. 따라서 오프라인에서 여러 개의 커밋을 수행했더라도 변경 사항을 모두 포착합니다.

정밀 업데이트 프롬프팅 (Surgical update prompting)
Generate 모드(첫 실행)와 Update 모드(이후 모든 실행)가 있습니다. 업데이트 프롬프트는 Gemini에게 변경된 파일의 영향을 받는 섹션만 수정하도록 명시적으로 지시하므로, 사용자가 수동으로 작성한 내용은 그대로 유지됩니다.

의미 탐지 (Significance detection)
이 기능은 Archie가 모든 작은 커밋마다 API 호출 비용을 낭비하는 것을 방지합니다. package.json 변경, 스키마/마이그레이션(schema/migration) 파일, 새로운 디렉토리, 또는 5개 이상의 파일을 수정하는 커밋과 같은 경우에만 작동합니다. 더 작은 커밋들은 재생성(regeneration)을 트리거하지는 않지만, 상태 포인터(state pointer)는 계속 앞으로 이동합니다.

알려진 한계점 (솔직하게 말씀드립니다)

• 임포트(Import) 분석이 정규 표현식(regex) 기반이어서, 동적 임포트(dynamic imports)와 재내보내기(re-exports)를 놓칠 수 있습니다.
• 아직 모노레포(monorepo)를 지원하지 않습니다.
• TypeScript가 아닌 코드베이스에서는 프롬프트 품질이 가변적입니다.

아직 초기 단계입니다. 며칠 전 출시 이후 npm 다운로드 수가 약 250회 정도이므로, 사람들에게 실제로 무엇이 유용한지 여전히 파악해 나가는 중입니다.

• GitHub: https://github.com/abhishek-sonje/archie
• 랜딩 페이지: https://archie.abhishekdev.tech
• 사용해 보기: npm i archie-ai

핵심 전제, 아키텍처 문서 형식, 또는 위의 기술적 결정 사항 등 무엇이든 좋으니 여러분의 의견을 진심으로 듣고 싶습니다. 댓글을 통해 어떤 내용이든 기쁘게 논의하겠습니다.