GitHub Copilot을 일주일 이상 사용해 본 사람이라면 그 고통을 알고 있을 겁니다.

새로운 기능을 추가하라고 요청하면 갑자기 파일이 사방에 생겨납니다. 핸들러가 잘못된 폴더에 들어가 있기도 하고, 존재해서는 안 되는 모듈에서 무언가를 가져와 임포트하기도 합니다. 기존 패턴과 전혀 다른 프론트엔드 코드를 작성합니다.

그리고 매번 AI가 망친 것을 고치는 데 20분을 소비합니다.

저는 그 것에 지쳤습니다. 그래서 이에 관한 무언가를 만들었습니다.

간단히 알려드립니다: 이것은 초기 버전입니다. 저는 여전히 개선하고 있으며, 상황이 바뀔 것이고, 프로젝트가 발전함에 따라 이 글을 계속 업데이트할 것입니다. 읽으실 때 뭔가 다르게 보인다면 — 아마도 그 이유일 겁니다. 괜찮죠? 괜찮습니다.

이게 대체 뭐예요?

Flow는 **모듈형 모놀리스(modular monolith)**입니다. 실제로 이것이 무엇을 의미하는지 알려드리겠습니다:

기능 하나 = 폴더 하나. Go 백엔드(핸들러, 서비스, 리포지토리, 모델)와 React 프론트엔드(컴포넌트, API 클라이언트, 테스트, esbuild config)가 단일 기능에 대해 모두 modules/<feature>/ 안에 존재합니다. 함께요. 7개의 디렉터리에 걸쳐 분리되지 않습니다.

이것은 일반적으로 backend/handlers/, backend/services/, frontend/components/, frontend/api/와 같이 구조를 짜서, 하나의 기능을 구성하는 모든 조각들을 찾는 것이 보물찾기처럼 느껴지는 것과는 정반대입니다.

콜로케이션(colocation)을 사용하면 폴더 하나만 열면 그 기능에 관한 모든 것이 바로 거기에 있습니다. 그리고 더 중요한 것은 — Copilot이 한 곳에서 전체 그림을 볼 수 있기 때문에, 어디에 무엇을 두어야 할지 추측하는 것을 멈춘다는 것입니다.

대부분의 코드베이스는 AI에게 혼란스럽습니다. 실제 일어나는 일은 다음과 같습니다:

1. "사용자 프로필 모듈을 추가해 줘"라고 말합니다.
2. Copilot이 코드를 생성합니다.
3. 백엔드는 handlers/에, 프론트엔드는 components/에 들어가서 — 이제 당신의 기능은 우주 전체로 분산됩니다.
4. 코드베이스의 컨벤션 대신 임의의 npm 패키지에서 패턴을 복사해 옵니다.
5. 한숨 쉬고, 모든 것을 삭제한 다음 수동으로 처리합니다.

익숙하게 들리시나요?

실제로 효과가 있는 세 가지 방법

1. AI에게 규칙을 알려주세요 (그것은 듣습니다)

VS Code에서는 레포지토리에 .github/copilot-instructions.md라는 파일을 넣을 수 있습니다. Copilot은 사용자가 채팅할 때마다 이 파일을 읽습니다.

저는 여기에 다음과 같은 내용을 채워 넣었습니다:

- 모든 기능의 코드는 MUST modules/<feature>/에 존재해야 함
- 하나의 모듈은 다른 모듈의 패키지를 직접 import해서는 안 됨
- React 컴포넌트는 2개 이상의 모듈에서 사용되는 경우에만 root components/에 위치해야 함

그게 전부입니다. 마크다운으로 된 단순한 지침일 뿐입니다. 그리고 Copilot은 실제로 그것을 따릅니다.

2. 환각이 아닌 스크립트를 제공하세요

AI가 새 모듈의 구조를 추측하게 두는 대신, 저는 쉘 스크립트(shell script)를 주고

제가 무언가를 구현하는 것을 마치면, 그냥 @reviewer review my changes라고 입력하면 모듈 경계(module boundaries), 임포트 규칙(import rules), 코딩 컨벤션(coding conventions)을 확인해 줍니다. 사소한 것들은 PR 리뷰가 필요 없습니다.

실제로 작동할까요?

네, 놀라울 정도로 잘 작동합니다.

며칠 전에는 @implementer add a blog module with CRUD endpoints라고 입력했습니다. 그러면 스캐폴드(scaffold) 스크립트를 실행하고, 모듈을 등록하며, Go 백엔드와 React 프론트엔드를 모두 빌드하고 테스트까지 실행했습니다. 약 30초가 걸렸습니다.

파일이 제자리에 있지 않은 곳은 없었습니다. 크로스-모듈 임포트도 없었습니다. 프론트엔드는 마치 원래 있어야 할 것처럼 api.ts 파일을 통해 API를 호출했습니다.

AI가 마법처럼 똑똑해진 것은 아닙니다. 단지 명확한 경계(clear boundaries)가 있었고, 궤도를 이탈할 수 없었던 것뿐입니다.

구성 요소 (What's in the Box)

만약 사용해보고 싶다면:

git clone https://github.com/ynwd/flow
cd flow
npm install
...

그런 다음 VS Code를 열고 Cmd+I를 누른 뒤, 모듈을 생성하라고 지시해 보세요. 어떤 일이 일어나는지 확인해 보세요.

이 저장소에는 다음 내용들이 포함되어 있습니다:

• 적절한 에러 래핑(error wrapping), DI(Dependency Injection), 테이블 기반 테스트가 적용된 Go 백엔드
• esbuild로 번들링된 React 18 + TypeScript 프론트엔드 (프로덕션 환경에서 webpack이나 vite 사용 안 함)
• Tailwind CSS v4
• 모듈 자체 등록 패턴 (수정해야 할 단일(monolith) 라우트 파일 없음)
• 모든 규칙이 담긴 .github/copilot-instructions.md
• 3가지 사용자 정의 에이전트 (implementer, reviewer, ask)
• 재사용 가능한 프롬프트 템플릿 3개
• 스캐폴딩(scaffolding), 마이그레이션(migrations), 공유 컴포넌트를 위한 3가지 도메인 스킬

솔직한 평가 (The Honest Take)

이것이 여러분의 코드베이스 이해도를 대체하는 것은 아닙니다. 여전히 무엇을 만들고 있는지 알아야 합니다.

하지만 AI 코딩에서 오는 **마찰(friction)**은 제거합니다. 실제 기능을 작성하는 대신 AI의 실수를 수정해야 하는 그 부분이요. 이것이 바로 이 시스템이 해결하는 문제입니다.

만약 Copilot을 더 큰 프로젝트에 사용하는 것에 대해 망설였거나, 시도해봤지만 좌절감을 느꼈다면 — 이 패턴을 사용해 보세요. 프레임워크 자체는 무엇이든 상관없습니다. 하지만 AI를 위해 저장소를 구조화한다는 아이디어? 이것은 오래 기억될 것입니다.

몇 주말 동안 만들었습니다. 유용하다고 생각되시면 저장소에 별표를 해주세요(Star the repo), 아니면 포크해서 자신만의 것으로 만들어 보세요. 즐겁게 배포하시길 바랍니다.