Skip to content

AGENTS.md

Latest commit

 

History

History
138 lines (103 loc) · 8.49 KB

AGENTS.md

File metadata and controls

138 lines (103 loc) · 8.49 KB
Raw

code-context-graph

A local code analysis tool that parses codebases with Tree-sitter and builds a knowledge graph.

MCP Server

The ccg MCP server registered in .mcp.json provides 17 tools:

  • 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
  • detect_changes, get_affected_flows, list_flows
  • get_annotation
  • get_doc_content, search_docs

ccg serve is the local stdio MCP entry point. Self-hosted HTTP mode is provided by the separate ccg-server binary, which serves /mcp, /health, /ready, /status, and /webhook. Webhooks are enabled in ccg-server when allowed repositories are configured with the --allow-repo flag. Per-repository branch filtering: --allow-repo "org/api:main,develop" (glob patterns; defaults to main/master when omitted). Compatible with GitHub (X-Hub-Signature-256) and Gitea (X-Gitea-Signature, X-Gitea-Event). Push event pipeline: receive push event -> automatic clone/pull -> graph build -> DB persistence. Graceful shutdown: SIGINT/SIGTERM propagates context cancellation to in-progress clone/build work.

Agent Skills (5)

Skill Description
/ccg Core build and search: parsing, graph build, query, search
/ccg-analyze Code analysis: impact radius, flow tracing, and change risk
/ccg-annotate Annotation system: AI annotation workflow and tag reference
/ccg-docs Documentation: generation, DB-backed discovery, and lint
/ccg-namespace Namespace isolation for multi-project graph data

Skill files are located under skills/ and are written so coding agents such as Codex and Claude Code can use them as slash-command style workflows.

Main commands:

  • ccg build [dir] - build the code graph (supports --exclude, --no-recursive)
  • ccg serve - start the local MCP server over stdio
  • ccg-server - start the self-hosted HTTP MCP/webhook server
  • ccg docs [--out dir] - generate Markdown documentation and the Wiki compatibility index
  • ccg search <query> - full-text search (includes annotations)
  • ccg lint [--strict] - check documentation quality
  • /ccg-annotate annotate [file|dir] - AI annotation generation workflow

Use .ccg.yaml to manage project defaults such as exclude patterns and DB settings.

Code Search Rules

When looking for code locations, related implementations, call relationships, impact radius, or architecture context, use ccg MCP tools and Agent Skills first.

  • For natural-language code understanding and module exploration, prefer the /ccg-docs skill: use search_docs to find relevant docs, then get_doc_content to read one.
  • For exact symbol locations, call relationships, and graph metadata, use ccg MCP query_graph, get_node, get_minimal_context, or the /ccg skill.
  • For annotation/keyword-based candidate search, use ccg MCP search or ccg search as a supplement.
  • For impact radius, flows, and change-risk analysis, prefer the /ccg-analyze skill and related MCP tools (get_impact_radius, trace_flow, detect_changes, get_affected_flows).
  • For simple string checks, file existence checks, or cases where the ccg index is missing or stale, use rg as a supplement. If needed, refresh the graph with ccg build . or ccg update ..

Documentation

See the guide/ directory for detailed documentation:

  • CLI Reference - all commands, flags, and config files
  • MCP Tools - 17 MCP tools, Agent Skills, AI-Driven Annotation
  • Annotations - annotation tags, examples, and search
  • Webhook - webhook sync, branch filtering, HMAC, graceful shutdown
  • Docker - Docker builds, MCP server, PostgreSQL deployment
  • Development - development guide, integration tests, project structure
  • Runtime Layout - ccg, ccg-server, and shared ccg-core ownership boundaries
  • Architecture - data flow, components, DB schema

Development Rules

  • TDD: Red -> Green -> Refactor
  • Tidy First: separate structural changes from behavioral changes
  • Use GORM queries only (no raw SQL)
  • Tests: CGO_ENABLED=1 go test -tags "fts5" ./... -count=1
  • Integration test: ./scripts/integration-test.sh (full Gitea + PostgreSQL + ccg Docker pipeline)

Code Writing Rules

When creating new code or making meaningful behavior changes to existing code, add CCG annotations as well.

Priority:

  • Use // @index ... when the package/file role should be discoverable.
  • Use // @intent ... for new public types/functions/methods, MCP handlers, CLI commands, and service methods.
  • Use // @param, // @return when input/output contracts matter.
  • Use // @requires, // @ensures when preconditions or guarantees matter.
  • Use // @sideEffect when the code mutates external state such as files, DB, network, cache, logs, or processes.
  • Use // @mutates when the receiver or argument values are modified.
  • Use // @domainRule for business rules, operational policies, and false-positive/false-negative criteria.
  • Use // @see when related handlers, services, or models exist.

Annotations must match the code behavior and should not exaggerate the explanation. Do not force annotations onto simple getters/setters or obvious one-line helpers.

Completion Checklist

After completing code generation or code modifications, run the following by default:

ccg build .
ccg docs --out docs
ccg lint

If the change modifies behavior or touches DB/search/parser/MCP handlers, also run Go tests:

CGO_ENABLED=1 go test -tags "fts5" ./... -count=1

For documentation-only changes, prioritize regenerating docs with ccg docs and running ccg lint. Code tests may be skipped depending on the change scope.

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.