어노테이션 스펙

태그 등급

@Domain

• 형식: <token> 또는 <token>/<subtoken>
• 다중: 쉼표로 (subscription/master, notification/trigger)
• lore.config.yaml 의 domains: 에 등록된 토큰만 허용
• 검증: lore check 가 알 수 없는 토큰을 거부

@BusinessLogic

• 한 줄 요약 (60자 권장)
• 시스템 동작이 아닌 비즈니스 의도를 적을 것
• ❌ “subscription 모델 정의”
• ✅ “valid_until 지나면 is_active=False, Celery 자동 갱신”

@History

데이터·정책 의미가 바뀌는 변경에만 추가합니다. 자세한 내용은 데이터 아카이올로지.

@History:
  - 2024-03-15: trial 7일 → 14일
  - 2024-11-02: valid_until NOT NULL 강제
  - 2025: 외부 매칭 SaaS 도입 시도 → 특허만 구매, 서비스 미적용

날짜는 YYYY, YYYY-MM, YYYY-MM-DD 모두 허용 — 정확한 일자가 기억 안 나는 과거 사건도 연도/연월만으로 기록할 수 있습니다.

@Connection

심볼 간의 호출·참조·트리거 연결을 multi-line bullet 으로 적습니다. L2 synthesize 의 “대표 플로우” 섹션 작성 1차 재료입니다.

@Connection:
  - FK: Candidate(OneToOne) → reverse: ai_profile
  - Writer: candidate/services/ai_profile_generator.py:37 generate_ai_profile()
  - Caller: Candidate.post_save signal / candidate/admins/candidate.py:215
  - Reader: candidate/services/real_matching_data.py:89 calculate_real_matching_score
  - Server-only: app 레벨 직접 노출 API 없음

권장 형식 (강제 아님):

• FK: <model>(<관계>) → reverse: <name>
• Writer: <path:line> <함수()> — 이 심볼을 쓰는 코드
• Reader: <path:line> <함수()> — 이 심볼을 읽는 코드
• Caller: <trigger> — signal · scheduler · 라우트 · 다른 함수
• Server-only / Client-only — 노출 경계

형식

Python (docstring)

class Subscription(models.Model):
    """
    @Domain: subscription/master
    @BusinessLogic: valid_until 지나면 is_active=False
    @Context: 자동 결제 실패 시 3일 grace 제공
    @History:
      - 2024-03-15: trial 7일 → 14일
    @Flow: auto-renewal, grace-period
    """

TypeScript (JSDoc)

/**
 * @Domain auth/profile
 * @BusinessLogic 구독 등급 + trial 남은일수 표기
 * @Flow profile-display
 */
export default function ProfileCard({ userInfo }: Props) { ... }

검증 규칙

• requireDomain: true (기본) → @Domain 누락 시 fail
• requireBusinessLogic: true (기본) → @BusinessLogic 누락 시 fail
• requireHistoryOnDataChange: warn|strict|off → @History 권장도 (heuristic)
• minSubstantiveLines: 5 → 5줄 이하 boilerplate 파일은 검사 skip