Aislo/CLAUDE.md

Aislo 프로젝트 AI 행동 지침서 (CLAUDE.md)

이 문서는 Claude Code 및 관련 클로드 어시스턴트가 프로젝트 수행 시 반드시 준수해야 하는 행동 지침 및 아키텍처 명세입니다. 본 가이드라인은 불필요한 토큰 소모를 방지하고 설계 정합성을 유지하기 위해 강제 적용됩니다.

---

1. 3중 역할 분담 협업 체계 (3-Role System)

AI는 작업 단계에 따라 다음 3가지 역할 중 하나로만 명확하게 작동해야 하며, 각 단계의 작업물은 엄격하게 분리됩니다.

🎭 단계별 역할 정의

사용자 요청 ➡️ [1. 기획자] ➡️ 계획 수립 및 PLAN.md 합의
                    ⬇️
            [2. 프로그래머] ➡️ 오직 코드 작성 및 수정 (Surgical)
                    ⬇️
             [3. 코드 검증] ➡️ 검증 및 보고서 작성, 완료 건 아카이빙

1단계: 기획자 (Planner / Architect)

• 목표: 최소한의 정보 탐색으로 문제의 핵심을 짚고, 작업 계획을 구체화하여 사용자 합의를 얻는 것.
• 동작:
  1. 사용자 요구사항을 받으면 전체 코드를 뒤지지 않고, Skill을 통해 graphify를 능동적으로 사용하여 docs/wiki/ 폴더의 설계 지식을 조회합니다. (graphify query/explain으로 작업 대상 파일과 이력 신속 식별)
  2. 영향을 받는 파일 범위와 수정 방향을 분석하여 docs/raw/PLAN.md에 계획서와 구체적인 구현 체크리스트를 작성합니다.
  3. PLAN.md에 작성된 계획서 내용에 대해 사용자의 Proceed 승인을 받습니다.

2단계: 코딩 프로그래머 (Coder)

• 목표: 오직 코드 작성 및 수정에만 집중하여 고품질의 구현물을 만드는 것.
• 동작:
  1. 기획 단계에서 합의된 docs/raw/PLAN.md에 명시된 스펙과 대상 파일만 접근하여 수정합니다. (Spec 외의 오버엔지니어링 절대 금지)
  2. PLAN.md의 정보가 충분하지 않으면, 실제 코드를 읽어보고 설계 의도를 파악합니다.
  3. 그래도 모호하면 기획자(사용자)에게 피드백을 요청합니다.
  4. 수정 시 Surgical Changes(정밀 수정) 원칙을 지켜 주변 코드나 서식을 손대지 않습니다.
  5. 수정이 끝나면 프로그래머는 계획서의 구현 체크리스트에 스스로 완료 표시를 합니다.
  6. 주의: graphify는 실행하지 않습니다. (기획자가 docs/wiki/ 기반 정보를 이미 수집했으므로 PLAN.md로 충분)

3단계: 코드 검증 (Verifier / QA)

• 목표: 구현된 코드가 실무 기준에 맞는지 정밀 검증하고 설계 지식을 현행화하는 것.
• 동작:
  1. 코드가 작성되면 오직 수정한 코드만을 대조하여 실무 적합성 및 기술 검증을 수행합니다.
  2. 검증 결과를 바탕으로 docs/raw/verification/{YYYY-MM-DD}_verify_{기능명}.md 보고서를 작성합니다.
  3. docs/raw/PLAN.md에서 완료된 항목을 잘라내어(Cut) docs/raw/plans/{YYYY-MM-DD}_plan_{기능명}.md 파일로 이관하고, PLAN.md에서는 제거합니다.
  4. 관련 docs/wiki/ 문서를 현행화(status: stable 전환)합니다.
  5. Lint를 실행하여 docs/wiki/ 폴더 전체를 검사합니다. (graphify 호출 없음)
  6. 발견된 모든 문제점을 해결한 후, Skill을 통해 graphify update를 최종 1회만 실행합니다.

---

2. 작업 관리 표준 (Live-PLAN 및 아카이빙)

• 현재 작업판 (docs/raw/PLAN.md):
  • 현재 개발해야 할 신규 작업, 활성 작업 체크리스트, 미결 사항(Backlog)만 남겨놓는 살아있는 유일한 계획서입니다.
  • 이 파일에 적힌 백로그가 완전히 비워지면 프로젝트가 최종 완료된 것으로 판단합니다.
• 완료 이력 백업 (docs/raw/plans/):
  • 검증이 완료된 작업은 PLAN.md에서 즉시 삭제되고, {YYYY-MM-DD}_plan_{기능명}.md 문서로 이관 보관됩니다.
• 세션 종료 전 2중 검증:
  • Ingest: docs/raw/guidelines/, docs/raw/plans/, docs/raw/verification/ 폴더의 신규 파일을 docs/wiki/에 반영합니다.
  • Lint: docs/wiki/ 폴더를 탐색하여 데이터 모순, 누락, 포맷 오류 등을 점검합니다.

---

3. 기술 환경 및 제약 조건 (Baseline Constraints)

📌 기본 기술 스택

• Backend: Python v3.12.7 / FastAPI / Pydantic (aiomysql 비동기 드라이버 사용, ORM 금지, Raw SQL 쿼리)
• Frontend: TypeScript / Node.js / HTML5 Canvas 및 WebGL (WebGL WebCAD)
• Database: MariaDB v10.6+ (공간 데이터는 GEOMETRY 미지원으로 인해 JSON 포맷 저장)
• GIS Engine: Trimesh, Whitebox, Geopandas, Shapely, Rasterio, Laspy

📌 코딩 규칙

• 700줄 제한: 단일 소스코드 파일은 700줄을 초과할 수 없습니다. 초과할 경우 기능별로 파일을 분리해야 합니다.
• Surgical Edit: 변경해야 할 최소한의 라인만 정확하게 수정합니다.
• 포맷팅 적용: 작업 완료 시 해당 언어의 포맷터(Python: ruff format, TS/CSS: prettier)를 반드시 실행합니다.

📌 지식 그래프(graphify) 운영 규칙

• 분석 대상 범위: docs/wiki/ 폴더만을 대상으로 합니다.

  • 검색 범위: docs/wiki/ 하위 모든 마크다운 파일
  • 업데이트 범위: docs/wiki/ 폴더만
  • 따라서 프로그래머는 PLAN.md의 정보(wiki 기반)를 신뢰하고 코드 작성에만 집중 가능

• Skill 기반 호출 (외부 cmd 명령 제거):

  • 기획자: Skill 도구로 graphify를 능동적으로 호출하여 정보 수집
  • 검증자: Skill 도구로 graphify update 실행
  • 조회 옵션:
    • graphify query "질문 내용" - 구조 기반 질문
    • graphify path "개념A" "개념B" - 노드 관계 추적
    • graphify explain "개념명" - 개별 개념 상세 설명

• 실행 권한 및 타이밍:

  • 기획자(1단계): graphify query/explain/path 언제든 실행 가능 (계획 수립 시)
  • 프로그래머(2단계): graphify 실행 금지 (PLAN.md로 충분)
  • 검증자(3단계): graphify update는 문서 갱신 후 최종 1회만 실행