팀에 AI 코딩 도구를 도입할 때 가장 먼저 부딪히는 문제는 '어떤 모델을 쓸까'가 아니다. '같은 패턴을 왜 매번 다시 설명하고 있나'다. 프로젝트가 바뀔 때마다 시스템 프롬프트를 새로 작성하고, 코드 리뷰 기준을 다시 주입하고, 테스트 컨벤션을 또 가르친다. 이 반복이 사라지지 않으면 AI는 도구가 아니라 매번 온보딩해야 하는 신입이다.
dev.to에 올라온 한 사례는 이 문제를 파일 단위로 해결한다. Cursor와 Claude Code의 설정을 12개의 재사용 가능한 파일로 정리한 것인데, 핵심은 '프롬프트'가 아니라 '툴체인 동작 자체를 바꾸는 설정'이라는 점이다. 크게 네 가지 영역으로 구성된다.
서브에이전트: .claude/agents/ 폴더에 위치하는 .md 파일들로, code-reviewer, test-generator, dependency-auditor, migration-runner 네 가지다. code-reviewer는 결함을 OWASP 태그와 함께 분류하고 머지 가능 여부까지 판정한다. 애매한 리뷰로 끝나지 않고 머지 버딕트를 강제하는 것이 핵심이다. migration-runner는 가장 공들인 결과물인데, ADD COLUMN NOT NULL 같은 위험한 마이그레이션을 감지하면 자동으로 3단계 안전 시퀀스로 재작성한다. 프로덕션 DB 락 이슈를 사람이 아니라 에이전트가 먼저 잡는다.
훅: PreToolUse 훅은 편집 전에 ESLint/Ruff/Clippy를 실행하고, 문제가 있으면 exit 2로 편집 자체를 막는다. Claude Code는 이 오류를 읽고 수정한 뒤 다시 시도한다. 사람이 개입하지 않아도 린트 통과가 전제조건이 되는 구조다.
스킬: long-running-tasks 스킬은 체크포인트 기반으로 진행 상태를 _state.json에 저장해, 멀티스텝 작업이 중간에 죽어도 이어서 실행된다. api-integration 스킬은 지수 백오프, 멱등성 키, 서킷 브레이커까지 프로덕션 수준의 API 통합 프로토콜을 강제한다.
여기서 냉정하게 짚어야 할 지점이 있다. 이 설정 파일들이 팀 워크플로우를 빠르게 표준화해주는 건 사실이다. 하지만 이 자동화가 빛을 발하려면 전제 조건이 있다. 팀이 그 위에 올라가는 기술 스택을 실제로 알고 있어야 한다.
GeekNews에서 화제가 된 'Choose Boring Technology, Revisited(2025)'는 바로 이 지점을 건드린다. Claude나 Copilot은 Kubernetes 마이크로서비스, GraphQL 페더레이션, 최신 JS 프레임워크까지 그럴듯하게 보이는 코드를 생성한다. 문제는 팀이 모르는 기술이 두 개 이상 겹치면 AI가 틀렸을 때 알아챌 방법이 없다는 것이다. deprecated API 사용, 보안 안티패턴, 프로덕션 부하에서야 드러나는 성능 문제—코드는 올바르게 보이고 네이밍도 맞고 에러 핸들링도 있었지만, 해당 기술에 익숙한 사람만 잡아낼 수 있는 방식으로 틀려 있었다.
두 사례를 겹쳐보면 실용적 긴장 구조가 드러난다. 설정 파일은 워크플로우 속도를 올린다. 하지만 AI가 생성한 코드의 품질이 높아질수록, 문제를 발견하기는 오히려 더 어려워진다. 나쁜 코드가 나빠 보이던 시대는 끝났다. 이제는 도메인을 충분히 이해해야만 미묘한 문제를 잡아낼 수 있다.
테크 리드 입장에서 이걸 팀 표준화에 적용하면 판단 기준이 하나 추가된다. '이 설정 파일을 적용할 기술 스택을, 팀이 AI의 오류를 검증할 수 있는 수준으로 알고 있는가?' Rails를 잘 아는 팀에 Rails 기반 설정 파일을 깔면 AI는 역량 증폭기가 된다. 팀이 처음 보는 프레임워크에 아무리 정교한 설정 파일을 깔아도, 에이전트가 틀린 마이그레이션 스크립트를 생성할 때 아무도 잡지 못한다.
실행 관점에서 팀 도입 순서를 정리하면 이렇다. 먼저 팀이 이미 잘 아는 기술 스택부터 설정 파일을 적용한다. migration-runner의 안전 시퀀스가 실제로 맞는지, code-reviewer의 OWASP 태깅이 우리 코드베이스에서 의미 있게 작동하는지 검증할 수 있는 영역에서 시작하는 것이다. 새로운 기술 스택에 AI 자동화를 얹고 싶다면, 그 기술을 먼저 배우는 데 실질적인 시간을 투자해야 한다. AI 도구가 '새 언어 + 새 프레임워크 + 새 인프라를 동시에 다룰 수 있을 것처럼' 느끼게 만든다는 점을 잊으면 안 된다.
워크플로우 자동화와 기술 이해는 함께 설계해야 할 두 축이다. 12개의 설정 파일은 팀의 반복 작업을 줄여주고, 코드 리뷰 기준을 일관되게 유지하며, 멀티스텝 작업의 신뢰성을 높인다. 하지만 이 파일들이 팀 표준화 도구가 되려면, 그 위에서 생성되는 코드를 팀이 판단할 수 있어야 한다는 조건이 먼저다. AI가 모르는 게 아니라 팀이 모르는 게 진짜 위험이다. 설정 파일은 내일 당장 깔 수 있다. 기술 이해는 그게 안 된다.