Backend Silk: 공유 백엔드 표준
간단하고 생산 수준의 코드를 작성하는 시니어 Python 백엔드 엔지니어 역할을 수행하세요. 이 스킬이 방지하고자 하는 두 가지 실패는 잘못된 구조(로직이 잘못된 계층에 있거나 아무도 필요로 하지 않는 파일)와 과도한 엔지니어링(작동하는 앱이 있기 전에 추상화 도입)입니다. 세 번째, 더 조용한 실패도 그만큼 비용이 많이 듭니다: 이전에 작동하던 동작을 조용히 누락시키는 변경 또는 리팩토링입니다.
컴패니언 스킬
명명 규칙: *-spider 스킬은 특정 종류의 프로젝트를 구축하고, *-silk 스킬은 모든 spider가 사용하는 공유 표준입니다. 이 스킬은 모든 백엔드가 공유하는 원칙을 담고 있습니다. 일치하는 컴패니언도 함께 로드하세요:
| 상황 | 함께 사용 |
|---|---|
| Flask / FastAPI / Django 프로젝트 | flask-spider / fastapi-spider / django-spider |
| Node.js / Express 프로젝트 | node-spider (여기의 규칙이 적용됨; Python 코드 샘플은 Python) |
| MCP 서버 또는 MCP 클라이언트 | mcp-spider |
| PostgreSQL, MySQL, SQLite (SQLAlchemy, Django ORM) | sql-silk |
| MongoDB | mongodb-silk |
| LLM, 임베딩, 벡터 저장소, RAG | rag-spider |
프레임워크 스킬은 프레임워크 메커니즘을 결정하고, 이 스킬은 원칙을 결정합니다. 충돌하는 경우 프레임워크 스킬의 구문과 이 스킬의 구조를 따르세요.
코드를 변경하기 전에
- 먼저 실제 코드를 읽으세요. 폴더 구조, 모델, 설정 및 변경하려는 파일을 확인하세요. 필드 이름, 함수 시그니처, 파일 이름 또는 임포트 경로를 추측하지 말고 읽으세요. (실제
expense_date대신 추측한date는 한 번에 스키마, 헬퍼 및 응답을 망가뜨렸습니다.) 설치된 라이브러리의 작동 방식이 확실하지 않을 때는 가정하지 말고 실제 API를 확인하세요. - 먼저 경로를 결정하세요. 기능의 경우 구현하기 전에 각 엔드포인트(메서드, 경로, 요청, 응답, 상태 코드, 인증)를 나열하세요.
- 범위는 요구 사항에서 나옵니다. 문제 설명이 필요한 것을 구축하세요. 아무도 요청하지 않은 추가 엔드포인트, 분석, 캐싱, 속도 제한, 재순위화, 비용 추적, 다운로드/검색 엔드포인트는 한 줄로 "나중에 가능"이라고 언급하고 구축하지 마세요.
- 작동하는 동작을 유지하세요. 함수를 다시 작성할 때는 현재 수행하는 작업(필터, 페이지 매김, 유효성 검사, 로깅, 응답 필드)을 나열하고 새 버전이 여전히 이 모든 작업을 수행하는지 확인하세요.
계층
routes -> helpers -> services -> database / external systems
| |
utils utils
| 폴더 | 소유 | 포함하지 말아야 할 것 |
|---|---|---|
routes/ (Flask 청사진, FastAPI 라우터, Django views.py + urls.py, MCP tools/) | URL, 메서드, 인증 종속성/데코레이터, 상태 코드, 응답 모델, 헬퍼에 대한 한 번의 호출 | 비즈니스 로직, 쿼리, 유효성 검사 코드, try/except, 로깅 |
helpers/ | 하나의 기능에 대한 비즈니스 로직(컨트롤러와 유사): 스키마를 넘어선 유효성 검사, 소유권 확인, 기능별 쿼리 및 필터, 서비스 오케스트레이션, 예상 실패를 HTTP 오류에 매핑, 응답 구축 | DB 세션 열기/닫기, 커밋/롤백, LLM 또는 SDK 클라이언트 생성 |
services/ | 각각 하나의 외부 시스템 또는 인프라 조각: DB 연결 및 일반 CRUD (db_service.py), LLM, 임베딩, 벡터 저장소, PDF, 이메일, 다른 저장소의 API | 기능별 비즈니스 규칙, HTTP 지식 (HTTPException, 상태 코드), 헬퍼 호출 |
utils/ | 여러 모듈에서 재사용되는 클래스 기반 코드: LogUtils, ErrorHandlers, AuthUtils, 순수 변환기 | 하나의 기능에서만 사용되는 코드, 외부 API 호출 |
schemas/ | Pydantic 요청/응답 모델 (Django: serializers.py) | DB 모델 |
models/ | 영속성 모델 | 비즈니스 로직 |
prompts/ | 코드로서의 프롬프트 템플릿 (LLM이 사용되는 경우에만) | .env의 프롬프트 |
config.py | .env에서 로드된 하나의 설정 객체 | 로직 |
표에서 따르는 규칙:
- 방향은 단방향입니다. Routes는 helpers를 호출하고, helpers는 services를 호출합니다. Service는 절대 helper를 호출하지 않으며, utility는 절대 helper를 호출하지 않습니다.
- 데이터베이스 분할. Helper는 기능 쿼리(필터, 검색, 소유권)를 구축하고, DB 서비스는 이를 실행하며 연결, 세션, 커밋 및 롤백을 담당합니다. 자세한 내용은
sql-silk/mongodb-silk를 참조하세요. Django의 경우 ORM이 DB 계층이므로db_service가 없습니다. - 통과(pass-through) 계층 없음. Helper가 서비스로만 전달한다면 helper를 삭제하고 서비스를 직접 호출하세요. 모든 파일은 그 존재 가치를 입증해야 합니다.
- Utils vs helpers. 여러 곳에서 사용됨 →
utils/. 하나의 기능에서 사용됨 → 해당 기능의 helper. - 실제 필요가 생겼을 때 폴더와 파일을 생성하고, 미리 생성하지 마세요. 하나의 함수가 새로운 폴더(
errors/,exceptions.py,core/)를 정당화하지 않습니다. 적합한 기존 클래스에 추가하세요. - 명명 규칙:
<domain>_routes.py(<domain>_router또는 Flask의 경우<domain>_bp포함),<domain>_helper.py→XHelper,<domain>_service.py→XService,<domain>_schema.py,<domain>_utils.py→XUtils,<name>_prompt.py→NAME_PROMPT. 클래스 이름은 항상 해당 폴더와 일치해야 합니다 (helpers/내부의class ExpenseService는 잘못됨).
전체 폴더 역할 및 시작 트리: references/architecture.md.
코드 규칙
- 클래스 기반 모듈. Helpers, services 및 utils는 클래스입니다. 무상태 코드에는
@staticmethod/@classmethod를 사용하고, 클래스가 종속성(예: 주입된 세션 또는 클라이언트)을 보유하는 경우에만 인스턴스를 사용하세요. Route 파일 및 Djangourls.py는 모듈 수준으로 유지됩니다. 두 개의 실제 구현 없이 상속, 추상 기본 클래스 또는 인터페이스를 강제하지 마세요. - 함수는 약 40-50줄로 유지하세요. 긴 함수를 동일한 클래스의 의미 있는 메서드로 분할하세요(예:
list_expenses→parse_filter_parameters+apply_expense_filters). 임의의 덩어리로 분할하지 마세요. _로 시작하는 함수 이름은 없습니다. 함수 내부에 정의된 함수는 없습니다. 중첩된 데코레이트된 함수 대신app.add_exception_handler(...)와 같은 명시적 호출로 핸들러를 등록하세요.- 모든 import는 파일 상단에, stdlib → 서드파티 →
app.*순서로 그룹화하세요. 함수 내부에서 import하여 순환 import를 수정하지 말고, 코드를 올바른 모듈로 이동하여 수정하세요. 유일한 예외는create_app()내부의 Flask 청사진 import입니다. - 수동으로 작성된 로직 대신 확립된 라이브러리 사용:
password-validator,email-validator/EmailStr, PyJWT, bcrypt, LangChain 로더 및 분할기,httpx. - 한 번만 검증하세요. Pydantic 스키마가 이미 규칙을 적용한다면 helper에서 다시 확인하지 마세요.
- 하나의 요청에서 동일한 것을 두 번 계산하지 말고, 빠르게 실패하세요. 비용이 많이 드는 검사 전에 저렴한 검사를 수행하세요 (bcrypt 해싱 전에 중복 이메일 확인).
- 하드코딩된 구성 없음: URL, 모델 이름, 제한, top_k, temperature 및 시크릿은
config.py에서 가져옵니다. - 데드 코드 없음: 사용하지 않는 함수, 사용하지 않는 import, 빈 플레이스홀더 파일 및
startapp잔재는 제거됩니다. - 모든 클래스 및 공개 메서드에 타입 힌트 및 한 줄 독스트링을 작성하세요. 이유가 명확하지 않은 경우에만 주석을 작성하세요.
- 예외를 절대 삼키지 마세요. 조치를 취할 수 있는 특정 예외를 포착하고, 나머지는 전역 핸들러에 도달하도록 두세요.
과도한 엔지니어링 확인
파일, 클래스, 계층, 종속성 또는 패턴을 추가하기 전에, 현재 요구 사항이 필요하고 이미 존재하는 것이 이 작업을 수행하는지 자문하세요. 다음은 모두 구축되었다가 제거된 것들입니다:
- 앱 실행 전 pydantic-settings 또는 검증 프레임워크 (빈 동결 데이터클래스 설정으로 충분)
- 하나의 오류에 대한 새로운 예외 모듈 또는 클래스
- 서비스만 호출하는 helper
- 귀하가 소유한 두 서비스 간의 RS256 키 쌍 (HS256 공유 시크릿으로 충분)
- 저장된 파생 값 (
total_tokenswhen input + output exist) - 포함된 목록이 작동하는 두 개의 컬렉션 또는 테이블
- 긴 프롬프트 및 긴 도구 설명
여러 디자인이 작동할 때는 여전히 프로덕션에 안전한 가장 간단한 디자인을 선택하세요.
요청 및 응답 스키마 (요약)
- 모든 엔드포인트는 알 수 없는 필드 및 서버 소유 필드를 거부하는 요청 스키마로 본문과 쿼리 매개변수를 검증합니다. 검증 후 코드는 검증된 객체만 사용합니다.
- 모든 성공적인 응답은 응답 스키마에서 구축됩니다: 리소스 자체 (
XResponse), 리스트{"items", "page", "page_size", "total", "total_pages"}또는 액션 결과 스키마 (TokenResponse). 엔벨로프나 핸들러에서 조립된 객체 리터럴은 없습니다. - 상태 코드는 성공과 실패를 전달합니다: 200 읽기/업데이트, 201 생성, 204 본문 없는 삭제, 오류는
ErrorResponse와 함께 전달됩니다. 실패에 200을 사용하지 마세요.
전체 계약 및 프레임워크별 스키마 위치: references/api-design.md.
오류 (요약)
- 모든 오류 응답은
assets/common_schema.py에서 하나의 형태를 가집니다:{"status": "error", "message": "...", "details": [{"field": "...", "message": "..."}]}(details는 필드 오류가 있는 경우에만) - Services는 일반 또는 라이브러리 예외를 발생시키고, helpers는 예상된 경우 HTTP 오류를 발생시킵니다.
utils/error_handlers.py의 하나의ErrorHandlers클래스는 종속성 오류를 매핑하고 다른 모든 것을 500으로 포착합니다. - 상태 코드: 400 잘못된 입력, 401 인증되지 않음, 404 누락 또는 다른 사용자의 레코드, 409 중복, 413 너무 큼, 422 스키마 검증, 424 자체 종속성 다운(데이터베이스, 벡터 저장소), 429 업스트림 속도 제한, 502 업스트림 오류 반환, 503 다른 서비스에 연결할 수 없음, 504 업스트림 시간 초과, 500 예상치 못한 오류. 실패에 200을 사용하지 마세요.
- 사용자는 짧고 안전한 메시지를 보며, traceback, 호스트, 연결 문자열 또는 키를 절대 볼 수 없습니다.
엣지 케이스 체크리스트 및 핸들러 패턴: references/errors-and-edge-cases.md. 저장소 간 호출: references/cross-repo-communication.md.
로깅 (요약)
하나의 LogUtils 클래스 (assets/log_utils.py)가 시작 시 .env의 LOG_LEVEL 및 LOG_TO_FILE에서 한 번 구성됩니다. 다른 모든 모듈은 logger = LogUtils.get_logger(__name__)만 수행합니다. 형식 %(asctime)s | %(levelname)s | %(name)s | %(message)s, 메시지는 Event | key=value, 시크릿 또는 개인 데이터 없음, 각 실패는 한 번만 기록됩니다. 자세한 내용: references/logging.md.
설정 및 보안 (요약)
.env에서 로드된 동결 데이터클래스가 있는config.py(assets/config.py);env.example은 플레이스홀더와 주석과 함께 커밋됨 (assets/env.example),.env는 절대 커밋되지 않음 (assets/gitignore).- 비밀번호: 등록 시에만
password-validator정책, bcrypt/werkzeug 해싱, 로그인 시 일반적인 "잘못된 이메일 또는 비밀번호입니다." - JWT:
.env의 시크릿, 사용자 ID는 확인된 토큰에서만 가져오고 요청 본문에서는 절대 가져오지 않습니다. - 모든 쿼리는 현재 사용자로 범위가 지정됩니다. 다른 사용자의 레코드는 404를 반환합니다.
자세한 내용: references/security.md. API 규칙 (메서드, 페이지 매김, 필터링, 검색 매개변수): references/api-design.md.
Git 및 테스트 (요약)
- 절대 커밋되지 않음:
.env, 키, 자격 증명, 업로드, 벡터 데이터, 로컬 데이터베이스, 로그, 가상 환경, 생성된 보고서. 마이그레이션은 이를 생성한 모델 변경과 함께 커밋됩니다. - 커밋 메시지는 Conventional Commits (
feat:,fix:,refactor:,chore:,test:,docs:,perf:)을 따르며, 커밋당 하나의 관심사, 저장소당 하나의 커밋입니다. - 테스트는 중요 경로를 다룹니다: 인증, 사용자 간 소유권, 유효성 검사, 오류 응답, 종속성 실패 (모의). 외부 서비스(LLM, 다른 저장소)는 모의 처리됩니다.
- 평가 (골든 데이터셋, 평가 스크립트, 보고서)는 명시적으로 요청된 경우에만 존재합니다.
rag-spider/mcp-spider참조.
자세한 내용: references/git-and-testing.md.
코드 체크리스트
- 계층이 존중됨; pass-through 파일 없음; 클래스 이름이 폴더와 일치
- 밑줄 시작 또는 중첩 함수 없음; import는 상단; 함수 ≤ ~50줄
- 기존 동작 유지 (필터, 페이지 매김, 유효성 검사, 응답 필드)
- 모든 엔드포인트에 요청 스키마 및 응답 스키마가 있음; 임시 응답 객체 없음
-
references/errors-and-edge-cases.md의 엣지 케이스가 올바른 상태 코드로 처리됨 -
config.py및env.example의 새 설정; 하드코딩 없음; 코드 또는 로그에 시크릿 없음 - 로깅이 적절한 위치에, 적절한 수준으로 추가됨
- 사용하지 않는 import 또는 데드 코드가 남아 있지 않음
참조 파일 (필요할 때만 읽기)
| 파일 | 읽을 때 |
|---|---|
references/architecture.md | 프로젝트 생성, 기능 폴더 추가, 코드가 속한 위치가 확실하지 않을 때 |
references/errors-and-edge-cases.md | 엔드포인트, 오류 핸들러 작성 또는 실패 경로 검토 시 |
references/cross-repo-communication.md | 한 서비스가 다른 저장소, MCP 서버 또는 외부 API를 호출할 때 |
references/logging.md | 로깅 설정 또는 검토 시 |
references/security.md | 인증, 비밀번호, JWT, 업로드, 시크릿, CORS |
references/api-design.md | 엔드포인트, 요청/응답 스키마, 페이지 매김, 필터, 검색 설계 시 |
references/git-and-testing.md | 커밋, PR 설명, 절대 커밋되지 않는 것, 테스트, 디버깅 접근 방식 시 |
에셋 파일 (프로젝트에 복사하고 적응)
템플릿을 선택적으로 복사하세요: 이 프로젝트가 현재 사용하는 부분만 유지하세요(.gitignore 섹션, .env.example 키, 설정 필드). 프로젝트에 없는 기능에 대한 남은 줄은 잡음이며 다음 독자를 오도합니다.
| 파일 | 생성 위치 |
|---|---|
assets/log_utils.py | app/utils/log_utils.py |
assets/common_schema.py | app/schemas/common_schema.py |
assets/config.py | app/config.py |
assets/env.example | .env.example |
assets/gitignore | .gitignore ("항상" 섹션에 더해 적용되는 표시된 섹션만) |