# Ccg Annotate

> code-context-graph — AI-driven annotation workflow. Add @intent/@domainRule/etc to code so search and RAG can find by business meaning.

- **Type:** Skill
- **Install:** `agentstack add skill-tae2089-code-context-graph-ccg-annotate`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [tae2089](https://agentstack.voostack.com/s/tae2089)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [tae2089](https://github.com/tae2089)
- **Source:** https://github.com/tae2089/code-context-graph/tree/main/skills/ccg-annotate

## Install

```sh
agentstack add skill-tae2089-code-context-graph-ccg-annotate
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# ccg-annotate — Annotation Workflow

Add structured business metadata to code. **This is what makes search and RAG actually useful.**

## Why Annotations Matter

- Enables domain search that text matching can't do: "payment" → finds functions with `@intent payment processing`
- Enriches RAG community summaries
- LLM can grasp intent without reading code → token savings
- Surfaces domain rules automatically during PR review

**Without annotations, ccg delivers only half its value.**

## Core Tags

| Tag           | WHAT vs WHY                         | Example                                  |
| ------------- | ----------------------------------- | ---------------------------------------- |
| `@intent`     | **WHY this function exists**        | `verify identity before granting access` |
| `@domainRule` | Specific business rule              | `lock account after 5 failures`          |
| `@sideEffect` | Real side effects (DB/network/file) | `writes to audit_log`                    |
| `@mutates`    | State changes                       | `user.FailedAttempts, session.Token`     |
| `@requires`   | Precondition                        | `user.IsActive == true`                  |
| `@ensures`    | Postcondition                       | `returns valid JWT with 24h expiry`      |
| `@index`      | One-line file/package summary       | `User authentication service`            |
| `@see`        | Related function or CCG ref         | `SessionManager.Create`, `ccg://auth-svc/internal/auth/token.go#ValidateToken` |

## Retrieval-Aware Tag Selection

Annotations are retrieval features, but they must stay truthful. Use the
specific tag that matches the code's role instead of stuffing keywords into
`@intent`.

| When you see this | Add this |
| ----------------- | -------- |
| File/package/module should be found as one unit | `@index` |
| Public function, handler, CLI command, service method, or UI workflow has a clear purpose | `@intent` |
| Policy, constraint, operational rule, or false-positive/false-negative criterion matters | `@domainRule` |
| DB/file/network/cache/log/process side effect exists | `@sideEffect` |
| Receiver or input state changes | `@mutates` |
| Caller-facing input/output contract matters | `@requires`, `@ensures` |
| Related implementation must be followed, especially across namespaces | `@see` |

Good retrieval annotations include the words a developer or LLM would naturally
use to ask for the code, while matching the implementation. For example, if a
graph component focuses a resolved `ccg://` node, say `graph viewer`, `ccg ref`,
and `node focus` in the appropriate `@index`/`@intent`. Do not add unrelated
terms just to raise score; broad terms make the wrong files rank higher.

## AI Workflow (`/ccg-annotate annotate `)

This is an agent skill workflow, not a `ccg` CLI subcommand. The CLI provides
`ccg example ` and `ccg tags` for writing guidance; the agent reads
and edits code directly.

### Step 1: Pick targets

- File path → that file only
- Directory → all source files
- **Skip**: tests, vendor, node_modules, generated

### Step 2: Analyze each function

Read the code and determine:

- What it does → first summary line
- File/package discoverability → `@index` when the file itself is a useful search target
- **Why it exists → `@intent`** for meaningful public/workflow entry points
- Business or operational rules → `@domainRule` (must be specific)
- Real side effects → `@sideEffect`
- State changes → `@mutates`
- Caller-facing contracts → `@requires`, `@ensures` when they matter

For cross-namespace behavior, explain the reason in the semantic tag and put the target in `@see`:

```go
// @sideEffect records token validation audit in auth-svc.
// @see ccg://auth-svc/internal/audit/token_audit.go#RecordTokenAudit
```

### Step 3: Write

- Add as comments directly above the declaration using language syntax (`//`, `#`)
- **Do NOT overwrite existing annotations**
- **Skip trivial functions** (getters/setters, obvious one-line wrappers)
- Do not add tags that do not match real behavior
- Do not repeat the same keyword across tags unless each tag adds distinct evidence
- Match the language of existing comments (Korean for Korean codebases, English for English)

### Step 4: Rebuild

```bash
ccg build .   # re-index with annotations
```

## Quality Rules (this is what really matters)

❌ **Bad annotation**:

```go
// @intent creates a user
func CreateUser(...) {}
```

WHAT only. Function name already tells you that.

✅ **Good annotation**:

```go
// @intent register new account for onboarding flow
// @domainRule email must be unique across all tenants
// @domainRule password must satisfy NIST 800-63B
// @sideEffect sends verification email
// @mutates users table, audit_log
func CreateUser(...) {}
```

WHY + business rules + side effects. Search and RAG become powerful.

## Annotation Priority

Don't annotate everything. Prioritize:

1. **Tier 1**: domain core (auth, payment, billing — business logic)
2. **Tier 2**: frequently searched (entry points, public APIs)
3. **Tier 3**: complex functions (high cognitive load)
4. **Skip**: getters/setters, simple wrappers, generated code

Use `ccg lint` `unannotated` category and pick top-priority functions from there.

## Retrieval Quality Checks

After adding annotations for a feature area, run a few natural-language
retrieve/search probes that match how an LLM or engineer would ask:

```bash
ccg build .
ccg search "graph viewer ccg ref node focus"
```

For MCP/Web UI retrieval, use `retrieve_docs` or the Wiki Retrieve mode. If the
expected file is missing, prefer improving the precise `@index`, `@intent`,
`@domainRule`, or `@see` evidence on that file over changing global scoring.

## Search Integration

Once annotated, `ccg search` indexes annotation text alongside code (see `/ccg` skill):

```bash
ccg search "결제"        # finds functions with "결제" in @intent (Korean)
ccg search "lock"        # finds functions with "lock" in @domainRule
```

## MCP Tools

| Tool             | Use                                  |
| ---------------- | ------------------------------------ |
| `get_annotation` | Fetch annotation/doc tags for a node |

## Prerequisites

Requires `ccg build .` first. (See `/ccg` skill.)

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [tae2089](https://github.com/tae2089)
- **Source:** [tae2089/code-context-graph](https://github.com/tae2089/code-context-graph)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-tae2089-code-context-graph-ccg-annotate
- Seller: https://agentstack.voostack.com/s/tae2089
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.