4. 코드 작성 규칙
파일명 규칙
- 파일명:
kebab-case사용 (예:readme-docs-plugin.ts,case-convert.ts) - 인터페이스/타입 파일:
kebab-case로 통일 - 테스트 파일: 대상 파일 옆에
*.test.ts로 배치 (예:src/exchange/parse.test.ts) - 빌드 스크립트:
scripts/하위에 위치 (readme-docs-plugin.ts)
TypeScript 강타입 규칙
any사용 금지:@typescript-eslint/no-explicit-any가 소스 코드에 명시되어 있으나,tool.ts의 handler 타입에 한해any가 허용됨 (MCP SDK 인터페이스 호환성 때문). 신규 코드에서는any사용을 지양하고unknown+ 타입 가드 사용- Zod 스키마: 모든 도구의 입력 스키마는
z.ZodRawShape로 타입이 고정됨 - 제네릭 활용:
toolDef<const TSchema extends z.ZodRawShape>()패턴으로 타입 안전한 스키마 정의 const타입 매개변수: Zod 스키마 정의 시const타입 매개변수를 사용하여 literal type 보존
도구(tool) 작성 패턴
모든 도구는 다음 구조를 따라야 합니다:
toolDef(): 타입 추론이 적용된 도우미 함수 (실제 동작은 단순 반환)defineTool():AnyToolDef타입으로 캐스팅 (server.ts에서 배열로 변환 시 사용)text():{ content: [{ type: "text", text: content }] }형태의 MCP ToolResult 생성 헬퍼
AnyToolDef에는 examples, guidelines, typeLabels, typeDefs, returnType,
returnDescription 필드도 남아 있습니다. 문서를 손으로 쓰게 되어 이제 아무도 읽지
않으므로 채우지 않습니다. toolDef() / defineTool() 시그니처가 변경 금지 대상이라
타입에만 남겨 둡니다 (09-safe-change-rules 참고).
입력 스키마 규칙 (OpenAI 도구 가이드)
도구 스키마는 OpenAI 호환 엔드포인트가 그대로 소비합니다(에이전트 키트가 MCP 도구를
ChatOpenAI에 연결합니다). 그래서
OpenAI 함수 호출 가이드를
따릅니다. strict 모드는 지원하지 않는 키워드가 하나라도 남으면 요청 전체를 거절하므로,
inputSchema에서 아래를 쓰지 않습니다.
따라오는 결과
- 모든 필드가
required입니다. 가이드가 "All fields inpropertiesmust be marked asrequired"를 요구합니다. 호출 쪽은 필드를 생략할 수 없고null을 넘깁니다. null은 "기본값을 쓰라"는 뜻입니다. 핸들러가null을undefined로 바꿔 도메인 계층(src/exchange/·src/tmdb/·src/system/)이 기본값을 적용합니다.- 기본값과 범위는
.describe()에 둡니다. 모델이 읽을 수 있는 자리는 여기뿐이고, 같은 내용을README.md와SKILL.md에 다시 적습니다. src/tools/openai-schema.test.ts가 이 규칙을 강제합니다. MCP SDK가 실제로 내보내는 JSON Schema를 검사하므로, 이 테스트를 통과하지 못하는 도구는 추가하지 않습니다.
단일 파일 최대 길이 제한
- 도구 정의 파일: 최대 200줄 권장 (도구가 많아지면 별도 파일로 분리)
- 핸들러 로직: 가능한 한 도구 정의 파일 내에 인라인으로 작성. 공통 로직이 필요하면 별도 유틸리티 함수로 추출
문서
README.md와 skills/<bin>/SKILL.md는 손으로 씁니다. 생성기도 pnpm readme 명령도
없습니다. 도구를 추가·변경하면 두 파일을 손으로 고치며, 스키마에서 빠진 기본값과
범위도 여기에 함께 적습니다.
import/export 규칙
- Named exports 사용 (default export 금지)
- Path alias:
@/*→src/*. 루트tsconfig.json의paths에 정의하며, 테스트는rstest.config.ts가 같은 별칭을 미러링함- 공유 키트는
@/common, 에이전트 키트는@/common/agent로 가져옴 (@/common은agent/를 재노출하지 않음)
- 상대 경로 vs 별칭: 다른 디렉토리를 참조하는 크로스 디렉토리 import는
@/사용 (예:server.ts→@/tools/index). 동일 디렉토리 내 형제 모듈은 상대 경로 유지 (예:./exchange) - 파일 확장자: 생략 (
moduleResolution: "Bundler"— tsc, tsup/esbuild, rstest 모두.ts파일을 해석). 전부 번들링되므로 런타임 확장자가 필요 없음 - Re-export:
export { tools } from "./exchange"형태로 필요한 것만 선별하여 re-export
주석 작성 규칙
- 도구 설명:
description필드에 한글로 간결하게 작성 - Zod describe: 모든 파라미터에
.describe()를 붙입니다. 선택이 아니라 필수입니다 —default와 범위 키워드를 스키마에서 빼는 대신.describe()가 모델이 그것을 읽는 유일한 자리입니다 - 코드 주석: 필수적인 이유를 설명할 때만 사용 (특히
eslint-disable주석에는 반드시 이유 명시) - 사용 시 주의사항: 도구 정의가 아니라
README.md와SKILL.md에 적습니다
비동기 처리 방식
- 모든 도구 핸들러는
async함수로 작성 - 에러는 핸들러 내부에서
try/catch로 처리하거나, CLI의handleCliError()에서 Zod 에러를 자동 포맷팅 - MCP 서버의 경우 SDK가 내부적으로 비동기 에러를 처리
전역 예외 처리
- CLI:
handleCliError()가ZodError를 감지하여 사용자 친화적 메시지로 변환 - MCP 서버:
server.ts에서 최상위catch로 프로세스 종료 처리 - 도구 핸들러 내부에서 발생한 예외는 MCP SDK가 자동으로
CallToolResult에러 응답으로 변환