암묵적 지식 코딩: 팀 관행과 AI 어시스턴트 사이의 누락된 레이어
Source: Dev.to
번역을 진행하려면 실제 번역하고자 하는 텍스트(기사 본문)를 제공해 주시겠어요?
본문을 주시면 원본 서식과 코드 블록, URL 등을 그대로 유지하면서 한국어로 번역해 드리겠습니다.
모든 엔지니어링 팀은 두 개의 코드베이스를 가지고 있다
- 명시적인 코드베이스 – 저장소에 있는 코드: 버전 관리되고, 리뷰를 거치며, 배포된다.
- 암묵적인 코드베이스 – 엔지니어들의 머릿속에 살아 있는 지식: 선호하는 패턴, 허용 가능한 단축키, 그리고 팀 고유의 “클린 코드” 정의.
신입 개발자는 몇 달에 걸쳐 암묵적인 코드베이스를 흡수한다. 이것이 모든 PR 코멘트를 형성하고, 같은 팀의 두 경험 많은 엔지니어가 독립적으로 작업할 때도 눈에 띄게 유사한 코드를 만들어 내는 이유를 설명한다.
암묵적 지식 – “우리는 말로 표현할 수 있는 것보다 더 많이 안다.”
— Michael Polanyi
소프트웨어 팀에서는 이러한 지식이 구두로나 리뷰 코멘트를 통해 강제되는 관습으로 나타나지만, 문서화되지는 않는다.
Next.js 프로젝트에서의 실제 예시
| 관습 | 기원 | 왜 중요한가 |
|---|---|---|
“데이터 패칭에 useEffect를 사용하지 않는다.” | 문서화되지 않은 규칙; 시니어 개발자가 리뷰에서 강제한다. | 서버 컴포넌트가 이제 데이터 패칭을 담당한다; 과거 useEffect 사용 시 레이스 컨디션이 발생했다. |
“Server Actions는 항상 ActionResult를 반환한다.” | 6개월 전 고통스러운 디버깅 사건 이후에 생겨난 관습. | 티켓, ADR, 문서가 없으며 오직 팀의 기억에만 존재한다. |
“Zod 스키마는 lib/schemas/에 두고, 컴포넌트와 함께 두지 않는다.” | 두 엔지니어가 같은 엔티티에 대해 충돌하는 스키마를 만들자, 테크리드가 PR 코멘트로 해결하면서 정해졌다. | 코드베이스 전반에 걸친 중복과 불일치를 방지한다. |
이것들은 부하를 견디는 관습이다. 규모가 커진 상황에서 이를 위반하면 코드베이스를 탐색하고, 유지보수하며, 이해하기가 훨씬 어려워진다.
왜 AI가 기존 전수 메커니즘을 깨는가
| 기존 메커니즘 | 작동 방식 | AI가 어떻게 파괴하는가 |
|---|---|---|
| 코드 리뷰 / 페어 프로그래밍 / 삼투 | 주니어 개발자는 반복적인 PR 피드백을 통해 관습을 배운다. | AI는 그 피드백 루프를 전혀 거치지 않고 코드를 생성한다. |
| 피드백 루프 | 작성자가 댓글을 받음 → 학습 → 내재화. | AI는 여러분의 레포지토리와의 이력이 없고, 지난 주의 댓글을 기억하지 못하며, 훈련 데이터에서 얻은 패턴(팀 관습과 다를 수 있음)을 기본값으로 사용한다. |
| AI 교육 | AI가 생성한 코드에 댓글을 남겨도 모델을 가르칠 수 없다; 같은 위반이 다음 대화에서도 다시 나타날 수 있다. | 모델은 해당 관습을 알지 못할 뿐, 무시하는 것이 아니다. |
| 양 | 주 3 PR → 관리 가능한 피드백. | 주 20 PR (AI 지원) → 피드백 루프가 과부하되고 위반이 전파된다. |
결과: 암묵적인 지식이 AI에게 보이지 않아 팀 관습과 충돌하는 코드가 생성된다.
해결책: 암묵적 지식을 구조화된 레이어로 외부화하기
규칙을 수명과 안정성에 따라 구분하여, 한 레이어를 업데이트해도 다른 레이어가 의도치 않게 덮어쓰여지지 않도록 합니다.
| 레이어 | 일반적인 수명 | 목적 | 예시 |
|---|---|---|---|
| L1 – 설계 철학 | 2–5 년 | 왜 결정이 이루어지는가. | “우리는 개발자 편의성보다 정확성과 가시성을 최적화합니다.” |
| L2 – 기술 결정 | 1–3 년 | 무엇을 선택했고 왜 그런지. | “Next.js App Router – Pages Router 패턴 사용 안 함.” |
| L3 – 구체적인 코딩 규칙 | 6–12 개월 | 어떻게 구현하는지. | 네이밍 규칙, 오류 처리 패턴, 보안 불변식, 테스트 구조, import 순서. |
| L4 – 도구별 설정 | 2–4 개월 | AI 도구를 위한 규칙이 위치하는 곳. | CLAUDE.md (index file: 3 directives + file references), .mdc files for Cursor, Steering Rules for Kiro. |
수명별로 구분하는 이유
- Claude Code 플러그인 설정(L4)을 업데이트해도 설계 철학(L1)이 절대 덮어쓰여서는 안 됩니다.
- 새 라이브러리(L2)를 도입해도 보안 규칙(L3)을 다시 작성할 필요가 없습니다.
각 레이어는 고유한 소유자, 업데이트 빈도, 그리고 영향 범위를 가집니다.
빠른 시작 프로세스 (몇 주 안에 결과, 몇 달이 아니라)
-
기존 암묵 지식 수집
- 마지막 20개의 PR을 검토합니다.
- 사소하지 않은 각 댓글에 대해(오타/포맷은 무시), 다음을 물어보세요: “이 규칙은 무엇을 강제하고 있나요?” 적어두세요.
-
시니어 엔지니어 인터뷰
- 물어보세요: “논의 없이 PR을 즉시 거부하게 만드는 조건은 무엇인가요?”
- 설명하기 가장 어려운 규칙들을 기록하세요.
-
“모두가 알고 있다”는 규칙 브레인스토밍
- “우리는 여기서 X를 절대 하지 않는다”라고 생각한 모든 것이 후보가 됩니다.
보통 30–60개의 항목이 나오며, 대부분은 문서화된 적이 없습니다.
각 항목 분류
| 질문 | 대상 레이어 |
|---|---|
| AI 도구를 바꿀 때 이것이 바뀌나요? | L4 |
| 프레임워크나 라이브러리를 업그레이드할 때 이것이 바뀌나요? | L3 |
| 이것이 1년 이상 지속된 기술 선택을 반영하나요? | L2 |
| 이것이 팀이 결정을 내리는 이유를 설명하나요? | L1 |
팁: 배치를 과도하게 고민하지 마세요. 잘못된 레이어에 있는 규칙이라도 없는 규칙보다 낫습니다.
Putting It All Together
- Create a repository (or folder) for the knowledge base.
- Add files per layer (e.g.,
L1_DesignPhilosophy.md,L2_TechDecisions.md,L3_CodingRules.md,L4_ToolConfig/). - Populate each file with the classified items from the exercise.
- Hook the AI tool to read the appropriate layer(s) at generation time (e.g., load
L4_ToolConfigfor immediate guidance, referenceL3_CodingRulesfor style enforcement, etc.). - Iterate – as new conventions emerge, add them to the appropriate layer; as libraries evolve, move items between layers as needed.
By externalising tacit knowledge into a structured, lifespan‑aware knowledge base, you give your AI assistant the context it needs to generate code that respects your team’s conventions, while preserving the valuable human‑driven wisdom that makes your codebase robust.
대부분의 팀이 틀리는 이유
팀은 종종 인간에게는 의미가 통하는 규칙을 작성하고 AI가 의도를 추론할 수 있다고 가정합니다. 실제로는 AI는 명시적이고 모호함이 없는 규칙을 필요로 합니다.
인간 중심 vs. AI 중심 문구
| 인간을 위해 작성된 경우 | AI를 위해 작성된 경우 |
|---|---|
| Server Actions에서 적절한 오류 처리를 사용하세요. 팀의 숙련된 엔지니어라면 이 의미를 알지만, AI는 모릅니다. | All Server Actions must return ActionResult. Never throw an exception from a Server Action. Return { success: false, error: string } for any failure case. The error field should be a user‑readable message, not a technical error string. 모든 Server Action은 ActionResult를 반환해야 합니다. Server Action에서 예외를 절대 발생시키지 마세요. 실패 상황에서는 { success: false, error: string }를 반환합니다. error 필드는 기술적인 오류 문자열이 아닌 사용자에게 읽히는 메시지여야 합니다. |
테스트: 코드를 한 번도 본 적 없는 개발자가 이 규칙을 정확히 처음에 따라 할 수 있나요? 만약 그렇다면 → AI 독자를 위해 작성된 것입니다.
같은 생성 작업을 규칙을 적용한 경우와 규칙 없이 실행하세요. 결과물을 팀의 품질 기준에 맞춰 평가하십시오.
AI가 여전히 규칙을 위반할 때
AI가 이미 규정된 규칙을 계속 위반한다면, 다음 세 가지 중 하나가 발생하고 있을 가능성이 높습니다:
- 잘못된 컨텍스트 – 예: 보안 규칙이 API‑routes 컨텍스트가 아니라 일반 가이드라인 파일에 존재하는 경우.
- 너무 추상적 – 구체적인 예시로 다시 작성하십시오.
Bad: “Never return raw Prisma objects.”
Good: “Never return raw Prisma objects. Instead, map them to DTOs. Example:return { id: user.id, name: user.name }.” - 규칙 충돌 – 서로 모순되는 두 규칙 때문에 AI가 임의로 선택하게 됩니다. 충돌을 식별하고 해결하십시오.
before/after 출력이 일관된 준수를 보여줄 때까지 반복하십시오. 실제로(여러 Next.js 프로젝트에서) 다음과 같은 과정을 보게 됩니다:
| 라운드 | 목표 |
|---|---|
| 1 | 가장 큰 격차를 드러내기 |
| 2 | 모호한 문구를 명확히 다듬기 |
| 3 (필요 시) | 엣지 케이스 충돌 해결 |
암묵적 지식 체계화의 숨은 이점
“우리의 Server Action 패턴”을 작성하면 팀이 암묵적 합의를 드러내게 됩니다. 종종 시니어 엔지니어들이 서로 다른 사고 모델을 가지고 있음을 발견하게 됩니다. 체계화 대화(≈30 분)는 모두를 정렬시키고, 명확한 규칙을 만들며, 숨겨진 마찰을 없애줍니다.
이 실천을 도입한 팀들의 보고된 성과
- 빠른 온보딩 – 신입은 코드를 뒤지지 않고 가이드라인 파일을 읽습니다.
- 명확한 PR 리뷰 – 리뷰어는 직관이 아니라 구체적인 규칙을 참고합니다.
- 디자인 논의에서 모호성 감소 – 예: “이것이 우리의 L2 기술 결정에 부합하는가?”
AI를 위해 작성한 규칙은 생생한 엔지니어링 핸드북이 되어 인간과 기계 모두에게 이익이 됩니다.
보상 타임라인
| 월 | 무슨 일이 일어나고 있나요 |
|---|---|
| 1 | 규칙을 정리하는 데는 시간이 걸립니다. 정의한 규칙에 따라 AI 출력 품질이 눈에 띄게 향상되지만, 여전히 빈틈이 존재합니다. |
| 3 | 핵심 컨벤션이 정리됩니다. 일반적인 경우에 AI 출력이 일관되게 패턴에 맞춰집니다. 위반 사례는 “흔하지만 명확하지 않음”에서 “드물고 즉시 눈에 띔”으로 변합니다. |
| 6 | 새로운 엔지니어가 더 빠르게 온보딩됩니다. AI와 엔지니어 모두 동일한 진실의 원천을 기준으로 작업합니다. |
시작하기
한 번에 모든 것을 규정화할 필요는 없습니다. 가장 높은 가치를 가진 규칙부터 선택하세요—위반될 때 가장 많은 정리를 요구하는 것들입니다. 대부분의 Next.js 프로젝트에서 이는 다음과 같습니다:
- API 라우트의 인증 패턴
- Server Action 반환 타입
- Zod 스키마 위치 및 사용법
이 세 가지 규칙을 AI 독자를 위해 작성하고, 테스트하고, 반복하세요. 간결하고 정확한 세 규칙 세트는 절대 충분히 정확하지 않은 80규칙 문서보다 더 많은 재작업을 없애줍니다.
Prompt: 코드베이스에 senior 개발자만 알고 있는 관례가 하나 있다면 무엇인가요? 댓글에 남겨 주세요—이것이 바로 기본 AI Dev OS 템플릿에 부족한 규칙들입니다.
리소스
- AI Dev OS 프레임워크 (Next.js 및 TypeScript용 규칙 템플릿 포함)
- 다음 시리즈 기사: AI‑Generated Code Has 2.74× More Security Vulnerabilities — Here’s the Data and What to Do (게시 시 링크가 추가될 예정)