AI가 탐색할 수 있도록 프로젝트 구조 잡기

AI 모델은 당신의 코드를 읽음으로써 추론한다. 지저분하고, 산만하고, 일관성 없는 프로젝트는 당신에게 어려운 만큼 그들에게도 어렵다. 완벽한 아키텍처가 필요한 건 아니지만, 몇 가지 습관은 즉시 보상을 준다:

• 예측 가능한 레이아웃을 유지하라. 소스는 한 곳에, 테스트는 소스 옆이나 소스를 거울처럼 따르는 위치에, 설정은 루트에.
• 명확하고 서술적인 이름을 써라. calculateMonthlyInvoiceTotal이 calc2보다 낫다. AI는 이름을 단서로 쓴다.
• 더 작은 파일을 선호하라. 200줄짜리 파일은 2,000줄짜리보다 정확하게 바꾸기 쉽다. 둘 모두에게.
• 관련된 것들을 한곳에 모아라. 한 기능의 코드, 스타일, 테스트가 함께 있으면, AI는 한 번 읽기로 맥락을 모은다.
• 명확한 진입점을 유지하라. 앱이 시작되는 분명한 한 곳은 AI가 프로젝트를 파악할 때 당겨볼 실마리를 준다.

전형적이고 AI 친화적인 레이아웃은 다음과 같은 모습일 수 있다:

my-app/
├── AGENTS.md            # project rules & context for the AI
├── README.md            # what the project is, how to run it
├── .env.example         # documents needed secrets (no real values)
├── .gitignore           # excludes .env, build output, node_modules
├── package.json         # scripts: dev, test, lint, build
├── src/
│   ├── features/
│   │   └── invoices/    # code + tests for one feature, together
│   ├── lib/             # shared helpers
│   └── index.ts         # entry point
└── tests/               # cross-cutting / integration tests

그 보상은 복리로 불어난다: 프로젝트가 AI가 탐색하기 쉬울수록, AI의 변경은 더 작고 더 외과적으로 된다. 잘 정돈된 리포는 AI가 서른 개를 헤집어 추측하는 대신 관련된 세 개의 파일만 건드리게 한다 — 그러니 더 작은 diff, 더 적은 사고, 그리고 당신이 실제로 읽을 수 있는 리뷰가 된다. AI가 광범위하고 초점 없는 편집을 하고 있다면, 진짜 범인은 프롬프트가 아니라 구조인 경우가 많다.