python + django에서 사용된 CLAUDE.md 양식

[nara04040]

참고용입니다.

추후 branch 생성을 하여 demo-context-engineering 문서에 맞는 형태로 정리할 예정입니다.

🔄 프로젝트 인식 및 컨텍스트

• 새로운 대화를 시작할 때 항상 PLANNING.md를 읽어 프로젝트의 아키텍처, 목표, 스타일, 제약사항을 이해한다.
• 새로운 작업을 시작하기 전에 TASK.md를 확인한다. 작업이 목록에 없다면 간단한 설명과 오늘 날짜를 추가한다.
• PLANNING.md에 설명된 일관된 명명 규칙, 파일 구조, 아키텍처 패턴을 사용한다.
• Python 명령 실행 시(단위 테스트 포함) venv(가상 환경)를 사용한다.
• 초기 DB 구조는 **docs/references/db-structure.sql**를 따른다. 만약, 초기 DB구조로 구현이 불가능한 사항이 생기면, 어떤 변경을 해야하며 또 그 이유는 무엇인지를 논리적으로 설명하면서 반드시, 사용자에게 승인을 구해야 한다.
• **docs/api-swagger.json**의 설계대로 동작하도록 구현해야 한다.
• 우선 auth api를 개발하지 않는다. 단, auth api 없이도 테스트를 수행하고, 프론트에서 요청할 수 있도록 같은 엔드 포인트로 토큰 발급용 임시 auth api 구현하여 사용한다.

🧱 코드 구조 및 모듈화

• 500줄을 초과하는 파일을 절대 만들지 않는다. 파일이 이 제한에 근접하면 모듈이나 헬퍼 파일로 분할하여 리팩토링한다.
• 기능이나 책임별로 그룹화된 명확하게 분리된 모듈로 코드를 구성한다.
  예를 들면, 에이전트의 경우 다음과 같이 구성된다:
  • agent.py - 메인 에이전트 정의 및 실행 로직
  • tools.py - 에이전트가 사용하는 도구 함수
  • prompts.py - 시스템 프롬프트
• 명확하고 일관된 import를 사용한다 (패키지 내에서는 상대 import 선호).
• 환경 변수를 위해 python_dotenv와 load_env()를 사용한다.

🔨 작업 진행 방식

• 작업을 의미있는 커밋 가능한 단위로 나누어 진행한다

  • 한 번에 모든 기능을 구현하지 말고, 논리적 단위로 나누어 작업
  • 각 단계가 완료되면 테스트를 실행하여 정상 동작 확인
  • 사용자가 원할 때 커밋할 수 있도록 완성된 상태 유지

• 작업 단위 예시:

  1. 모델 정의 → 마이그레이션 파일 생성 → 모델 테스트
  2. Serializer 구현 → Serializer 단위 테스트
  3. View/ViewSet 구현 → API 엔드포인트 테스트
  4. URL 라우팅 설정 → 통합 테스트

• 각 작업 단위 완료 시:

  • 구현한 내용 요약 제공
  • 테스트 실행 결과 공유
  • 다음 작업 단위 예고

• 절대 하지 말아야 할 것:

  • ❌ 여러 기능을 한꺼번에 구현
  • ❌ 테스트 없이 다음 단계로 진행
  • ❌ 미완성 상태로 다음 작업 시작

🧪 테스트 및 신뢰성

• 새로운 기능에 대해 항상 Pytest 단위 테스트를 작성한다 (함수, 클래스, 라우트 등).
• 로직을 업데이트한 후, 기존 단위 테스트의 업데이트가 필요한지 확인한다. 필요하다면 업데이트한다.
• 테스트는 메인 앱 구조를 반영하는 /tests 폴더에 위치해야 한다.
  • 최소한 다음을 포함한다:
    • 예상 사용에 대한 테스트 1개
    • 엣지 케이스 1개
    • 실패 케이스 1개

✅ 작업 완료

• 작업을 완료한 직후 TASK.md에 완료된 작업을 표시한다.
• 개발 중 발견된 새로운 하위 작업이나 TODO를 TASK.md의 "작업 중 발견 사항" 섹션에 추가한다.

📎 스타일 및 규칙

• Python을 주 언어로 사용한다.
• PEP8을 따르고, 타입 힌트를 사용하며, black으로 포맷팅한다.
• 데이터 검증을 위해 Django REST Framework의 Serializer를 사용한다.
• API에는 Django REST Framework를, ORM에는 Django ORM을 사용한다.
• 데이터베이스로는 PostgreSQL을 사용한다.
• 모든 함수에 Google 스타일의 docstring을 작성한다:

  def example():
      """
      간단한 요약.
  
      Args:
          param1 (type): 설명.
  
      Returns:
          type: 설명.
      """

📚 문서화 및 설명

• 새로운 기능이 추가되거나, 의존성이 변경되거나, 설정 단계가 수정될 때 README.md를 업데이트한다.
• 명확하지 않은 코드에 주석을 달고 모든 것이 중급 개발자에게 이해 가능하도록 한다.
• 복잡한 로직을 작성할 때, 인라인 # 이유: 주석을 추가하여 무엇을 하는지가 아닌 왜 하는지를 설명한다.

🧠 AI 동작 규칙

• 누락된 컨텍스트를 가정하지 않는다. 불확실할 때는 질문한다.
• 라이브러리나 함수를 임의로 만들지 않는다 – 알려진, 검증된 Python 패키지만 사용한다.
• 코드나 테스트에서 참조하기 전에 파일 경로와 모듈 이름이 존재하는지 항상 확인한다.
• 명시적으로 지시받거나 TASK.md의 작업의 일부가 아닌 한 기존 코드를 삭제하거나 덮어쓰지 않는다.

중요 지시사항 알림

요청받은 것만 한다; 더도 말고 덜도 말고.
목표 달성에 절대적으로 필요한 경우가 아니라면 파일을 생성하지 않는다.
항상 새 파일을 만드는 것보다 기존 파일을 편집하는 것을 선호한다.
사용자가 명시적으로 요청하지 않는 한 문서 파일(*.md)이나 README 파일을 생성하지 않는다.