2장 AI와 일하는 저장소를 만든다

AI 코딩 도구의 성능은 모델 이름만으로 결정되지 않는다. 저장소 안에 무엇을 읽을지, 어떤 명령을 실행할지, 무엇을 건드리지 말아야 할지가 명확해야 한다. 이 프로젝트의 AGENTS.md는 짧은 운영 계약이다. 실제 파일은 Goal·Commands·Rules·Done means 구조이며, 핵심 취지를 줄이면 다음과 같다.

# 핵심 운영 원칙 요약
- Run `npm test` after domain changes.
- Keep the default path offline and deterministic.
- Never send fixture contacts to external services.
- A change is done after test, capture, build, verify.

요청 하나에 여러 위험한 변경을 섞지 않는다. “폼을 추가하고 DB를 바꾸고 메일도 실제로 보내 줘”보다 “입력 계약과 테스트를 먼저 추가해 줘”가 검토하기 쉽다. AI가 수정한 뒤에는 설명보다 diff와 테스트 결과를 본다.

저장소 구조는 역할이 보이게 단순하게 유지한다.

public/       브라우저 화면
src/          서버, 도메인 규칙, AI 어댑터
test/         실행 가능한 기대
fixtures/     가상의 재현 데이터
figures/      실제 화면 캡처와 설명 그림
scripts/      캡처·빌드·검증
books/        원고

프롬프트 검토 체크

AI에게 파일을 만들라고 하기 전에 “기존 구현을 먼저 읽고 가장 작은 변경 계획을 말해 달라”고 한다. 출력 형식까지 지정하면 검토 비용이 줄어든다. 예를 들어 변경 파일, 위험, 실행할 테스트를 세 항목으로 보고하게 한다. 비밀값이나 실제 고객 데이터를 프롬프트에 붙이지 않는다.