Skip to content

Commit 1020f4c

Browse files
tae2089tae2089
committed
feat: add ccg CLI tool documentation and annotation workflow guide
1 parent 528d3e7 commit 1020f4c

1 file changed

Lines changed: 159 additions & 0 deletions

File tree

‎skills/ccg.md‎

Lines changed: 159 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,159 @@
1+
---
2+
name: ccg
3+
description: code-context-graph CLI — build code knowledge graphs, search by annotations, execute Cypher queries
4+
user-invocable: true
5+
---
6+
7+
# code-context-graph CLI Skill
8+
9+
A local code analysis tool that parses codebases via Tree-sitter into a knowledge graph with 15 language support, annotation-powered search, and Apache AGE Cypher queries.
10+
11+
## Subcommands
12+
13+
| Command | Description | Example |
14+
|---------|-------------|---------|
15+
| `build [dir]` | Parse directory, build graph + search index | `ccg build .` |
16+
| `build --graph [dir]` | Build + sync to Apache AGE graph DB | `ccg build --graph .` |
17+
| `build --embed [dir]` | Build + generate vector embeddings | `ccg build --embed .` |
18+
| `update [dir]` | Incremental sync (changed files only) | `ccg update .` |
19+
| `status` | Show graph statistics (nodes/edges/files) | `ccg status` |
20+
| `search <query>` | FTS keyword search (includes @annotations) | `ccg search "authentication"` |
21+
| `search --semantic <q>` | Vector similarity search | `ccg search --semantic "payment flow"` |
22+
| `query <cypher>` | Execute Cypher query on AGE graph | `ccg query "MATCH (n:Function) RETURN n"` |
23+
| `annotate [file\|dir]` | AI-generate annotations for code | `ccg annotate internal/analysis/` |
24+
25+
## Execution
26+
27+
Parse the user's input after `ccg` and run via Bash:
28+
29+
```bash
30+
./ccg {subcommand} {args}
31+
```
32+
33+
If the binary doesn't exist, build it first:
34+
35+
```bash
36+
CGO_ENABLED=1 go build -tags "fts5" -o ccg ./cmd/ccg/
37+
```
38+
39+
## When no arguments provided
40+
41+
Show available commands:
42+
43+
```
44+
Available ccg commands:
45+
ccg build [dir] — Build code knowledge graph
46+
ccg update [dir] — Incremental update
47+
ccg status — Graph statistics
48+
ccg search <query> — Full-text search (annotations included)
49+
ccg query <cypher> — Execute Cypher query (requires AGE)
50+
ccg annotate [file|dir] — AI-generate @annotations for code
51+
```
52+
53+
## Annotate Command
54+
55+
`ccg annotate` is NOT a CLI binary command — it is an AI-driven workflow executed by Claude.
56+
57+
When the user runs `ccg annotate [file|dir]`, Claude should:
58+
59+
### Step 1: Read target files
60+
- If a file path is given, read that file
61+
- If a directory is given, find all source files (`.go`, `.py`, `.ts`, `.java`, etc.)
62+
- Skip test files, vendor, node_modules
63+
64+
### Step 2: Analyze each function/class/file
65+
For each declaration, read the code and determine:
66+
- **What it does** (→ summary line above declaration)
67+
- **Why it exists** (→ `@intent`)
68+
- **Business rules it enforces** (→ `@domainRule`)
69+
- **Side effects** (→ `@sideEffect`: DB writes, API calls, file I/O, notifications)
70+
- **What state it changes** (→ `@mutates`: fields, tables, caches)
71+
- **Prerequisites** (→ `@requires`: auth, valid input, active state)
72+
- **Guarantees** (→ `@ensures`: return conditions, post-state)
73+
- **File/package purpose** (→ `@index` on package declaration)
74+
75+
### Step 3: Write annotations
76+
- Add annotations as comments directly above the declaration
77+
- Use the language's comment syntax (`//` for Go, `#` for Python, etc.)
78+
- Do NOT overwrite existing annotations — only add missing ones
79+
- Do NOT add trivial annotations (e.g., `@intent returns the name` for `getName()`)
80+
81+
### Step 4: Rebuild
82+
After annotating, run `ccg build .` to re-index with new annotations.
83+
84+
### Annotation Quality Rules
85+
- `@intent` should describe WHY, not WHAT (not "creates user" but "register new account for onboarding flow")
86+
- `@domainRule` should be specific business logic, not generic validation
87+
- `@sideEffect` only for actual side effects (DB, network, file, notification)
88+
- `@index` should summarize the module's responsibility in one line
89+
- Skip getters/setters/trivial functions — annotate functions with business meaning
90+
- Write annotations in the same language as existing code comments (Korean if Korean, English if English)
91+
92+
### Example output
93+
94+
```go
95+
// @index User authentication and session management service.
96+
package auth
97+
98+
// AuthenticateUser validates credentials and creates a session.
99+
// Called from login API handler.
100+
//
101+
// @param username user login ID
102+
// @param password plaintext password (hashed internally)
103+
// @return JWT token on success
104+
// @intent verify user identity before granting system access
105+
// @domainRule lock account after 5 consecutive failed attempts
106+
// @domainRule locked accounts auto-unlock after 30 minutes
107+
// @sideEffect writes login attempt to audit_log table
108+
// @sideEffect sends security alert email on 3rd failed attempt
109+
// @mutates user.FailedAttempts, user.LockedUntil, user.LastLoginAt
110+
// @requires user.IsActive == true
111+
// @ensures err == nil implies valid JWT with 24h expiry
112+
func AuthenticateUser(username, password string) (string, error) {
113+
```
114+
115+
## Smart Behaviors
116+
117+
### Auto-rebuild when stale
118+
If `ccg.db` doesn't exist or the user asks to analyze the project, run `ccg build .` first.
119+
120+
### Suggest Cypher queries
121+
When the user asks graph-related questions, suggest and execute appropriate Cypher:
122+
123+
| User intent | Suggested Cypher |
124+
|-------------|------------------|
125+
| "What calls this function?" | `MATCH (a)-[:CALLS]->(b {name: 'X'}) RETURN a.qualified_name` |
126+
| "Impact of changing X" | `MATCH ({name: 'X'})-[*1..3]-(affected) RETURN DISTINCT affected.qualified_name` |
127+
| "Path from A to B" | `MATCH path = (a {name: 'A'})-[:CALLS*]->(b {name: 'B'}) RETURN path` |
128+
| "Dead code" | `MATCH (n:Function) WHERE NOT ()-[:CALLS]->(n) RETURN n.qualified_name` |
129+
| "Most called functions" | `MATCH ()-[:CALLS]->(n) RETURN n.name, count(*) AS c ORDER BY c DESC LIMIT 10` |
130+
| "Module dependencies" | `MATCH (a)-[:CALLS]->(b) WHERE a.file_path STARTS WITH 'X' RETURN DISTINCT b.file_path` |
131+
132+
### Annotation-aware search
133+
When the user asks about business concepts, use FTS search which includes annotation content:
134+
- `@intent` — function purpose/goal
135+
- `@domainRule` — business rules
136+
- `@sideEffect` — side effects
137+
- `@mutates` — state changes
138+
- `@index` — file/package level description
139+
140+
Example: user asks "결제 관련 코드" → `ccg search "결제"` finds functions annotated with payment-related @intent/@domainRule.
141+
142+
### Multi-column Cypher
143+
When RETURN has multiple values, use `--columns N`:
144+
145+
```bash
146+
ccg query "MATCH (a)-[:CALLS]->(b) RETURN a.name, b.name" --columns 2
147+
```
148+
149+
## Graph Schema
150+
151+
Vertex labels: `Function`, `Class`, `Type`, `Test`, `File`
152+
153+
Edge labels: `CALLS`, `IMPORTS_FROM`, `INHERITS`, `IMPLEMENTS`, `CONTAINS`, `TESTED_BY`, `DEPENDS_ON`, `REFERENCES`
154+
155+
Vertex properties: `node_id`, `qualified_name`, `name`, `kind`, `file_path`, `language`, `start_line`, `end_line`
156+
157+
## Supported Languages (15)
158+
159+
Go, Python, TypeScript, Java, Ruby, JavaScript, C, C++, Rust, C#, Kotlin, PHP, Swift, Scala, Lua, Bash

0 commit comments

Comments
 (0)