[AI 활용법 4] 가드레일 — 모듈화·성능·UI를 AI에게 맡길 때
AI가 만든 코드가 다음 주에도 살아남게 만드는 규칙
시리즈 4편(완결). AI에게 코드를 맡기면 빠르게 잘못된 방향으로 갈 수 있다. 가드레일은 속도를 줄이는 장치가 아니라, 방향을 유지시키는 장치다.
1. 모듈화 — 단일 파일 함정
LLM은 한 파일에 모든 걸 몰아넣는 경향이 있다. 짧은 컨텍스트에서 “동작하는 코드 한 덩어리”를 내놓기가 쉬우니까. 그런데 그 덩어리는 다음 PR에서 모두가 싫어하게 된다.
기준선:
- 한 파일 300~500줄을 넘으면 분리 검토
- 한 함수 50줄을 넘으면 책임 분리 검토
- 3단계 이상 중첩이면 조기 반환 또는 헬퍼 분리
- 컴포넌트가 렌더 + 데이터 페칭 + 전역 상태 처럼 2가지 이상의 책임이면 분리
프런트엔드는 구조(JSX) / 스타일 / 로직, 백엔드는 Controller / Service / Repository / Domain / DTO 로 계층을 분리. 사용자가 “단일 파일로 만들어줘”라고 명시한 경우에만 예외.
2. 성능 — Lightweight-first
“일단 만들고 나중에 최적화”가 아니라 “처음부터 가벼운 구조를 기본값으로”.
LLM은 의외로 무거운 라이브러리 추천을 잘 한다. 막아 두자:
- 작은 유틸 하나를 위해 거대 라이브러리 추가 금지
- 표준 라이브러리·플랫폼 API를 우선 고려
- 현재 문제보다 2단계 이상 앞선 추상화 금지 (YAGNI)
- 측정 없이 최적화하지 않는다 — 프로파일러로 병목 확인 후 개선
성능 예산 예시:
| 메트릭 | 기준 |
|---|---|
| LCP | 2.5s 이하 |
| INP | 200ms 이하 |
| CLS | 0.1 이하 |
| 초기 JS 번들 | 200KB(gzip) 이하 |
ROI 순서: 네트워크 → 렌더링 → 알고리즘 → 마이크로 최적화. 마지막 단계에서 시간을 쓰는 사람은 대개 처음 단계를 빼먹은 경우다.
3. UI/UX — 모바일·작은 화면은 기본값
LLM에게 UI를 시키면 1280px 데스크톱만 잘 만든다. 명시적으로 말해야 한다:
- 모바일 퍼스트 — 320px에서 동작하는 레이아웃부터
- 터치 영역 최소 44×44px (WCAG / Apple HIG / Material 공통)
- 고정 픽셀 남용 금지 —
rem,em,%,vw,clamp() - safe-area:
env(safe-area-inset-*) - 가로 스크롤이 의도치 않게 생기지 않게
상태는 5가지를 항상 고려: idle / loading / empty / error / success. “빈 상태(empty state)” 를 잊지 않는 것이 가장 자주 빠지는 디테일.
4. 보안 — 프롬프트는 코드보다 먼저 새어 나간다
LLM에게 코드를 맡길 때 가장 큰 보안 사고는 LLM이 생성한 코드의 버그 가 아니라 LLM에게 _보낸 컨텍스트에 시크릿이 섞인 사고_ 다.
체크리스트:
- 시크릿은 절대 코드·커밋·로그·프롬프트에 노출하지 않는다
.env는.gitignore,.env.example만 커밋~/.ssh,~/.aws,~/.gnupg는 애초에 에이전트 워크 경로에서 제외- (이걸 자동화한 도구가 PathSentinel)
- 사용자 입력은 신뢰하지 않는다 — SQLi / XSS / Command Injection / SSRF 기본 방어
- 의존성 추가 시 typosquatting 확인
5. Git Identity — AI가 커밋 작성자가 되지 않게
AI에게 커밋·PR·이슈를 시키더라도 author와 committer는 사람이다. 자동으로 다음을 끼워 넣지 않게 한다:
Co-Authored-By: Claude ...🤖 Generated with Claude Code- “AI generated” 류 푸터
GitHub contribution 그래프는 사람의 것으로 귀속되어야 한다. 사용자가 명시적으로 요청한 경우에만 attribution을 추가.
6. README — 사용자 가시 변경에는 항상 갱신
다음 중 하나라도 해당하면 AI가 README를 갱신하게 만든다:
- 사용자가 바로 쓸 수 있는 신규 기능 추가
- 기존 기능의 사용법·API·옵션 변경
- 설치·실행·빌드·배포 절차 변경
- 환경변수·설정 키 변경
- 지원 플랫폼·런타임 버전 변경
내부 리팩터링만 한 경우(외부 동작 불변)에는 갱신하지 않아도 된다. “애매하면 사용자에게 묻는다” 가 디폴트.
우선순위 충돌 시
지침이 충돌할 때의 순서:
- 안전 및 법적 준수
- 정직성
- 사용자의 명시적 지시
- 프로젝트별
CLAUDE.md - 글로벌
CLAUDE.md - 일반적 엔지니어링 모범사례
이 순서를 시스템 프롬프트에 박아 두면, AI가 모호한 상황에서 혼자 돌아 들어가는 일이 줄어든다.
한 줄 요약
AI에게 잘 시키는 기술의 절반은 “잘 시키는 것”이고, 나머지 절반은 “하지 말 것의 목록” 이다.
이전 편: AI 활용법 3 — 자율모드 시리즈 시작: AI 활용법 1 — 정직성
시리즈 4편 한눈에
- 정직성 — 거짓말하지 않는 AI 운영
- 컨텍스트 관리 — Obsidian, 메모리, 핸드오프
- 자율모드 — 안전한 위임의 기술
- 가드레일 — 모듈화·성능·UI를 AI에게 맡길 때