컨벤션 프롬프트: AI 코드 변경을 레포에 자연스럽게 섞기
I’m happy to translate the article for you, but I’ll need the full text you’d like translated. Could you please paste the content (excluding the source line you already provided) here? Once I have it, I’ll keep the source link at the top and translate the rest into Korean while preserving all formatting, markdown, and technical terms.
문제
보조에게 “그냥 기능만 추가해”라고 요청해 본 적이 있다면, 그 고통을 알 수 있을 겁니다:
- 한 번도 사용해 보지 않은 새로운 폴더 구조를 추가합니다.
- 코드 형식은 거의 레포와 비슷하지만, 완전히 일치하지는 않습니다.
- 팀이 의도적으로 피했던 패턴을 만들어 냅니다.
그 결과가 반드시 잘못된 것은 아니지만, 낯선 코드가 됩니다. 낯선 코드는 비용이 많이 드는 코드입니다.
Source: …
솔루션: 컨벤션 프롬프트
컨벤션 프롬프트는 작은 재사용 가능한 지시문 블록으로, 모든 변경 사항이 마치 몇 달 동안 코드베이스에 몸담아 온 사람이 작성한 것처럼 보이게 합니다.
- 대부분의 어시스턴트는 문제 해결은 뛰어나지만, 여러분만의 문제 해결 방식과 일치시키는 데는 평범합니다.
- 여러분의 레포에는 이미 문화가 존재합니다(네이밍 컨벤션, 오류 처리 규칙, 로깅 스타일, 선호 라이브러리, “여기서는 하지 않는다” 제약, 아키텍처 경계 등).
- 컨벤션 프롬프트는 그 문화를 한 곳에 모아 모든 요청에 붙여 주어, 스타일 + 아키텍처 계약 역할을 합니다.
작성 방법
실제로 사용할 수 있을 만큼 짧게, 그러나 흐름을 방지할 만큼 구체적으로 유지하세요. 20–60줄 정도를 목표로 하며, 섹션별로 구분합니다:
- 프로젝트 구조 – 폴더, 모듈, 경계.
- 코드 스타일 – import, 네이밍, TypeScript 설정, lint 규칙.
- 런타임 컨벤션 – 오류, 로깅, 트레이싱, 메트릭.
- 테스트 기대치 – 테스트 위치, 프레임워크, 모킹 방식.
- 출력 형식 – diff‑only, 파일 목록, 혹은 단계별 계획.
템플릿 (복사 & 수정)
CONVENTIONS (read first, follow strictly)
Architecture
- Don’t introduce new top‑level folders.
- Keep business logic in /src/domain.
- Keep I/O (HTTP, DB) in /src/adapters.
- No cross‑imports from adapters → domain.
Code style
- TypeScript, ESM. Prefer named exports.
- Prefer early returns over nested ifs.
- Don’t change unrelated formatting.
- Use existing utilities instead of adding new helpers.
Errors & logging
- Never swallow errors.
- Throw AppError(code, message, cause?).
- Log with logger.info|warn|error({ ...context }, message).
Testing
- Use Vitest.
- Tests live next to files as *.test.ts.
- Prefer fakes over heavy mocks.
Output
- Provide:
1) A brief plan (3–6 bullets)
2) A unified diff only (no extra commentary)
- If any convention conflicts with the request, ask a clarifying question before editing.마지막 줄은 “비상시” 조항으로, 자신감에 찬 오류를 방지합니다.
기존 규칙 추출
이것을 처음부터 작성할 필요는 없습니다. 다음에서 추출하세요:
.editorconfig,eslint,prettier,ruff,go fmt규칙tsconfig.json(엄격성, 모듈 설정)- 기존 엔드포인트/서비스에서 패턴 찾기
- 테스트 레이아웃 및 모킹 스타일
- 리뷰어가 좋게 평가한 최근 PR
반복해서 나타나는 규칙만 적어두세요; 리뷰 시간을 가장 많이 절약할 수 있습니다. 예시:
- “새로운 의존성을 추가하지 마세요.”
- “새로운 추상화 레이어를 도입하지 마세요.”
- “관계 없는 코드를 리팩터링하지 마세요.”
예시 코드 조각
레포지토리에 표준 오류 처리 패턴이 있다면, 짧은 예시를 포함하세요:
// Example error handling pattern
try {
const user = await repo.getUser(id);
if (!user) throw new AppError('NOT_FOUND', 'User not found');
return user;
} catch (err) {
logger.error({ err, id }, 'getUser failed');
throw err;
}어시스턴트는 인간처럼 이것을 복사할 것입니다.
프롬프트 사용 예시: 샘플 요청
Task
POST /api/projects/:id/archive를 추가하여 프로젝트를 보관 처리하고 업데이트된 프로젝트를 반환합니다.- 기존 인증 미들웨어를 재사용합니다.
- 프로젝트가 존재하지 않을 경우 404를 반환합니다.
- 테스트를 추가합니다.
Context
- 기존 프로젝트 라우트는
src/adapters/http/routes/projects.ts에 있습니다. - 프로젝트에 대한 도메인 로직은
src/domain/projects/에 있습니다.
좋은 요청 예시:
[Paste CONVENTIONS here]
Task
- Add POST /api/projects/:id/archive
- Reuse the existing auth middleware
- Return 404 if project doesn’t exist
- Add tests컨벤션과 두 파일 경로만 있으면 충분합니다; 긴 설명은 필요하지 않습니다.
프롬프트를 저장하는 실용적인 방법
- Snippet file in your editor (가장 빠름).
- Repository file like
PROMPTS/conventions.md(팀에 가장 적합). - Seed message in your assistant workspace (반복 세션에 가장 적합).
팀은 보통 옵션 2를 선택하여 프롬프트를 코드처럼 검토할 수 있습니다.
최소 차이점
변경 사항을 자연스럽게 섞고 싶다면, 작은 차이를 목표로 하세요:
- “변경을 가능한 적은 파일에 국한하세요.”
- “필요하지 않은 한 코드를 옮기는 것을 피하세요.”
- “파일을 수정하지 않았다면 import 순서를 바꾸지 마세요.”
다음과 같은 제약을 추가하세요:
- “헬퍼를 추가하기 전에 기존 것이 있는지 찾아 재사용하세요.”
- “관련 없는 코드를 재포맷하지 마세요.”
- “린터가 요구하지 않는 한 따옴표/세미콜론을 바꾸지 마세요.”
차이점만 요청하세요; 목표는 리뷰어가 약 2 분 안에 검토할 수 있는 PR을 만드는 것입니다.
결론
Conventions Prompt는 어시스턴트를 더 똑똑하게 만드는 것이 아니라, 그들의 출력물을 예측 가능하고, 검토 가능하며, 팀‑호환하게 만드는 것입니다.
이번 주에 한 가지만 한다면: 약 30줄 정도의 Conventions Prompt를 작성하고 다음 다섯 개의 코딩 작업에 첨부하세요. 미래의 당신(그리고 검토자)에게 눈에 띌 것입니다.
— Nova