Skip to content

CLAUDE.md

Latest commit

 

History

History
83 lines (63 loc) · 5.94 KB

CLAUDE.md

File metadata and controls

83 lines (63 loc) · 5.94 KB
Raw

code-context-graph

코드베이스를 Tree-sitter로 파싱하여 지식 그래프를 구축하는 로컬 코드 분석 도구.

Follow the global prompt rules first. This file adds project-specific skill routing for a project that uses the agent-team CLI (github.com/tae2089/agent-team) as its durable work ledger.

MCP 서버

.mcp.json에 등록된 ccg MCP 서버가 18개 도구를 제공합니다:

  • parse_project, build_or_update_graph, run_postprocess
  • get_node, search, query_graph, list_graph_stats, list_namespaces, get_minimal_context
  • get_impact_radius, trace_flow, list_cross_refs
  • detect_changes, get_affected_flows, list_flows
  • get_annotation
  • get_doc_content, search_docs

HTTP 모드 (--transport streamable-http)에서는 /health 및 /webhook 엔드포인트도 제공합니다. Webhook은 --allow-repo 플래그로 허용 리포지토리를 설정하면 활성화됩니다. 레포별 브랜치 필터링: --allow-repo "org/api:main,develop" (glob 패턴, 미지정 시 main/master 기본). GitHub (X-Hub-Signature-256) 및 Gitea (X-Gitea-Signature, X-Gitea-Event) 호환. Push 이벤트 수신 → 자동 clone/pull → 그래프 빌드 → DB 저장 파이프라인. Graceful shutdown: SIGINT/SIGTERM 시 진행 중인 clone/build에 context cancel 전파.

CLI Skills (4개)

Skill 설명
/ccg 코어 빌드 & 검색 — 파싱, 그래프 빌드, 쿼리, 검색
/ccg-analyze 코드 분석 — 영향 반경, 플로우 추적, 데드코드, 아키텍처
/ccg-annotate 어노테이션 시스템 — AI 어노테이션 워크플로우, 태그 레퍼런스
/ccg-docs 문서 — 문서 생성, RAG 인덱싱, lint

주요 커맨드:

  • ccg build [dir] — 코드 그래프 빌드 (--exclude, --no-recursive 지원)
  • ccg search <query> — 전문 검색 (어노테이션 포함)
  • ccg docs [--out dir] — 마크다운 문서 생성
  • ccg lint [--strict] — 문서 품질 체크
  • ccg annotate [file|dir] — AI 어노테이션 생성

.ccg.yaml로 exclude 패턴, DB 설정 등을 프로젝트 기본값으로 관리할 수 있습니다.

문서

상세 문서는 guide/ 디렉토리를 참조하세요:

  • CLI Reference — 전체 명령어, 플래그, 설정 파일
  • MCP Tools — 18개 MCP 도구, Skills, AI-Driven Annotation
  • Annotations — 어노테이션 태그, 예시, 검색
  • Webhook — Webhook sync, 브랜치 필터링, HMAC, graceful shutdown
  • Docker — Docker 빌드, MCP 서버, PostgreSQL 배포
  • Development — 개발 가이드, Integration test, 프로젝트 구조
  • Architecture — 데이터 흐름, 컴포넌트, DB 스키마

개발 규칙

  • TDD: Red → Green → Refactor
  • Tidy First: 구조적 변경과 행위 변경 분리
  • GORM 쿼리만 사용 (raw SQL 금지)
  • 코드 정렬: 종류별 그룹화가 아니라 "타입 + 그 타입의 생성자·메소드"를 붙여 두는 응집 관례를 따른다 (상세: guide/development.md §Declaration order)
  • 테스트: CGO_ENABLED=1 go test -tags "fts5" ./... -count=1
  • Integration test: ./scripts/integration-test.sh (Gitea + PostgreSQL + ccg Docker 전체 파이프라인)

Skill Routing

  • When writing, modifying, or reviewing code, apply coding-quality-guardrails as the quality gate.
  • When debugging bugs, regressions, flaky behavior, or failing tests, use diagnosing-bugs before changing behavior.
  • Before implementing new logic with branching, side effects, resource lifecycles, or ordering constraints, use flow-design and keep the design note in the task workspace.
  • When designing module boundaries, refactoring, or shaping interfaces, use codebase-design.
  • When aligning terminology or modeling the domain, use domain-modeling.
  • When a plan is fuzzy, high-impact, or lacks testable acceptance criteria, use planning-grill to sharpen scope, acceptance, and failure modes before decomposing it.
  • For multi-step or multi-agent work, use decompose-and-dispatch to split the work into bounded units. Use execute-dispatch-unit only for a clearly assigned unit with scope, dependencies, and verification.
  • When preparing context for human or AI code review, use ready-code-review; do not use it to perform the review itself.
  • To record a session, distill completed work into a replayable recipe, or replay a recipe.yaml, use session-recipe.

agent-team Routing

agent-team bundles its own skills; restrict them as follows so methodology stays single-sourced:

  • Use only agent-team's CLI operation skills (the agent-team-* prefix: run/task/message/inbox/sync/event commands), and load agent-team-shared before any command-specific one — it defines the state directory, global flags, and error handling they all assume. Never use its recipe-* and persona-* skills — the skills routed above own all methodology, even where an excluded skill looks like a closer match (worker checkpoints → execute-dispatch-unit's Ledger Checkpoints; plan sharpening / recipe-agent-team-planning-grill → planning-grill; decomposition → decompose-and-dispatch; architecture → codebase-design; terminology → domain-modeling).
  • When executing an assigned unit, follow execute-dispatch-unit for scope, verification, and reporting; its Ledger Checkpoints section defines which agent-team-* calls to make.
  • When planning, decompose-and-dispatch owns decomposition and executor mapping, and its Durable Ledger section defines the run/task registration calls.
  • Do not route by the word "recipe": here it means a replayable session recipe (session-recipe, recipe.yaml); agent-team's recipe-* skills are excluded above.