code-context-graph — Annotation System

AI-driven annotation workflow for adding structured metadata to code. Annotations are indexed and searchable via FTS.

Subcommands

Command	Description	Example
annotate [file|dir]	AI-generate annotations for code	ccg annotate internal/analysis/
example [language]	Show annotation writing example	ccg example go
tags	Show all annotation tag reference	ccg tags

MCP Tools (1)

Tool	Description
get_annotation	Get annotation and doc tags for a specific node

Available Tags

Tag	Purpose	Example
@index	File/package description	@index Payment processing service
@intent	Why this function exists	@intent verify credentials before session creation
@domainRule	Business rule	@domainRule lock account after 5 failures
@sideEffect	Side effects	@sideEffect sends notification email
@mutates	State changes	@mutates user.FailedAttempts, session.Token
@requires	Precondition	@requires user.IsActive == true
@ensures	Postcondition	@ensures session != nil
@param	Parameter description	@param username the login ID
@return	Return description	@return JWT token on success
@see	Related function	@see SessionManager.Create

AI Annotation Workflow

ccg annotate is NOT a CLI binary command — it is an AI-driven workflow executed by Claude.

When the user runs ccg annotate [file|dir], Claude should:

Step 1: Read target files

• If a file path is given, read that file
• If a directory is given, find all source files (.go, .py, .ts, .java, etc.)
• Skip test files, vendor, node_modules

Step 2: Analyze each function/class/file

For each declaration, read the code and determine:

• What it does (→ summary line above declaration)
• Why it exists (→ @intent)
• Business rules it enforces (→ @domainRule)
• Side effects (→ @sideEffect: DB writes, API calls, file I/O, notifications)
• What state it changes (→ @mutates: fields, tables, caches)
• Prerequisites (→ @requires: auth, valid input, active state)
• Guarantees (→ @ensures: return conditions, post-state)
• File/package purpose (→ @index on package declaration)

Step 3: Write annotations

• Add annotations as comments directly above the declaration
• Use the language's comment syntax (// for Go, # for Python, etc.)
• Do NOT overwrite existing annotations — only add missing ones
• Do NOT add trivial annotations (e.g., @intent returns the name for getName())

Step 4: Rebuild

Do not invoke /ccg-build automatically. Report that reindexing is pending and that the user must explicitly name ccg-build in a new request.

Annotation Quality Rules

• @intent should describe WHY, not WHAT (not "creates user" but "register new account for onboarding flow")
• @domainRule should be specific business logic, not generic validation
• @sideEffect only for actual side effects (DB, network, file, notification)
• @index should summarize the module's responsibility in one line
• Skip getters/setters/trivial functions — annotate functions with business meaning
• Write annotations in the same language as existing code comments (Korean if Korean, English if English)

Example Output

// @index User authentication and session management service.
package auth

// AuthenticateUser validates credentials and creates a session.
// Called from login API handler.
//
// @param username user login ID
// @param password plaintext password (hashed internally)
// @return JWT token on success
// @intent verify user identity before granting system access
// @domainRule lock account after 5 consecutive failed attempts
// @domainRule locked accounts auto-unlock after 30 minutes
// @sideEffect writes login attempt to audit_log table
// @sideEffect sends security alert email on 3rd failed attempt
// @mutates user.FailedAttempts, user.LockedUntil, user.LastLoginAt
// @requires user.IsActive == true
// @ensures err == nil implies valid JWT with 24h expiry
func AuthenticateUser(username, password string) (string, error) {

Searching Annotations

Annotations are indexed in FTS and searchable via ccg search (see /ccg skill):

• @intent — function purpose/goal
• @domainRule — business rules
• @sideEffect — side effects
• @mutates — state changes
• @index — file/package level description

Example: user asks "결제 관련 코드" → ccg search "결제" finds functions annotated with payment-related @intent/@domainRule.