목차

AI가 잘 따라가지 못하는 영역

[사용자] “내가 관찰하기에는 파일의 이름이라든지, 파일 안에 위치한 물리 전개 구조 이런 것들도 어느 정도 영향을 미치는 것 같았어. 물론 네가 그걸 다 따라주지는 않더라고.”

파일 내부 레이아웃

• import 순서 (외부 → 내부 → 상대경로)
• 파일 내 배치 (types → constants → hooks → handlers → render)
• 함수 정의 순서 (public → private, 또는 호출 순서)
• export 방식 (named vs default, 하단 모아서 vs 선언과 함께)

왜 못 따라가나

[Claude] “폴더 구조는 한 번 보면 명확합니다. 파일 내부 레이아웃은 ‘암묵적 규칙’인 경우가 많습니다. 저는 훈련 데이터에서 본 가장 빈번한 패턴으로 기본값이 잡혀 있고, 기존 파일을 봐도 의식적으로 추출하지 않으면 그냥 제 습관대로 씁니다.”

효과적이었던 방법

1. Exemplar 파일 지정

“새 파일은 이 파일 구조 그대로 따라해”

2. 명시적 규칙

“import 순서는 이렇게, 파일 내 순서는 이렇게”

3. 즉각 피드백

“여기 순서 틀렸어, 이렇게 해” — 다음부터 좀 더 신경 씀

샘플 프로젝트 + 문서 전략

[사용자] “이런저런 패턴들이 다 나와 있는 샘플 프로젝트를 만들고, 그 패턴에 대한 문서까지 작성한 다음, 문서 안에 ‘이러이러한 패턴은 이 샘플 프로젝트의 어디어디를 참고하세요’라고 참조를 달아놓으면, 뭔가를 구현할 때 ‘이 패턴을 참조해라’라고만 얘기해도 타고타고 가서 제대로 잘 해줄 수 있으려나?”

구조 예시

1
2
3
4
5
6
7

/patterns
  /README.md          ← 패턴 인덱스 + 참조 링크
  /examples
    /state-management.ts
    /error-handling.ts
    /component-structure.tsx
    /file-layout.ts

README.md 예시

1
2
3
4
5
6
7

## 상태 관리
- Zustand store 구조: `examples/state-management.ts` 전체
- 액션 네이밍: 같은 파일 15-30줄

## 컴포넌트 구조
- 파일 내 배치 순서: `examples/component-structure.tsx`
- Props 타입 정의 방식: 같은 파일 1-20줄

사용 방법

“상태 관리 패턴 참조해서 새 store 만들어줘” → AI가 README 읽고 → 해당 파일 읽고 → 그 구조 따라감

한계

[Claude] “참조 체인이 길어지면 컨텍스트 소비가 큽니다. 100%는 여전히 아니고, 샘플 프로젝트 유지보수 비용도 발생합니다.”

권장

시작은 작게. 가장 자주 어긋나는 패턴 3-5개만 먼저 문서화, 효과 보이면 확장.

AI 컨텍스트도 유지보수 대상

[사용자] “결국 내가 원하는 대로 움직이게 하기 위한 컨텍스트들을 넣어주는 것도 결국 프로젝트 유지보수의 한 부분이 되는 거네.”

기존 유지보수 영역

• 코드
• 테스트
• 문서
• 인프라

AI 시대 추가 영역

• AI가 패턴을 따르게 하는 컨텍스트
• 예제 프로젝트
• 패턴 문서
• CLAUDE.md 같은 세션 설정

계산 공식

1

AI 써서 절약하는 시간 vs (AI 컨텍스트 유지보수 시간 + 결과물 검토 시간 + 수정 시간)

[Claude] “이게 플러스가 되는 프로젝트가 있고, 마이너스가 되는 프로젝트가 있습니다. 지금 AI 도구들이 ‘생산성 혁명’처럼 마케팅되는데, 이런 숨겨진 비용은 잘 언급 안 됩니다. 당신처럼 직접 해본 사람만 압니다.”

현실적 타협

크리티컬한 몇 가지만 명시하고, 나머지는 주기적으로 정리하는 게 나을 수 있음.

100% 맞추려면 거의 한 줄씩 확인해야 하고, 그게 “그냥 내가 하고 말지” 상황이 됨.

목차 / 다음글