API Surface With Anvien
Use this skill for route handlers, MCP/RPC tool handlers, generated contracts, response shape drift, route consumers, and API-impact decisions.
This skill is a workflow gate for API-surface work. It is not a command router. When a concrete Anvien command is needed, choose it directly from the generated Command Selection Guide.
Command Choices
| Need |
CLI |
MCP |
| Route handlers, consumers, middleware, flows |
anvien api route-map [route] --repo <repo> --json |
route_map |
| MCP/tool definitions and linked flows |
anvien api tool-map [tool] --repo <repo> --json |
tool_map |
| Response shape drift against consumers |
anvien api shape-check [route] --repo <repo> --json |
shape_check |
| Route/API blast radius |
anvien api impact [route] --repo <repo> --json |
api_impact |
| Route impact via generic impact |
anvien impact route <route> --repo <repo> --json |
impact with target_type=route |
| MCP tool impact via generic impact |
anvien impact tool <tool> --repo <repo> --json |
impact with target_type=tool |
| Exact handler file context |
anvien context file <path> --repo <repo> |
context with target_type=file |
| Exact handler symbol context |
anvien context symbol "<handler>" --repo <repo> |
context with target_type=symbol |
| Broad API discovery |
anvien query api "<concept>" --repo <repo> |
query with target_type=api |
MCP tool names use underscores: route_map, tool_map, shape_check, api_impact. CLI commands use hyphenated subcommands under anvien api. Do not invent CLI commands by reusing MCP underscore names as top-level Anvien commands.
Workflow
- Refresh the graph with
anvien analyze --force before graph-based API work.
- Use
query api for broad route/tool discovery only when the exact route or tool is unknown.
- Use route-map/tool-map to find handlers, consumers, flows, and handler-file
handlerFile projection data.
- Open handler files with
context file when you need symbol tree, file dependencies, linked tests, or unresolved handler-file sites.
- Use shape-check before changing response contracts or generated Web contracts.
- Use API impact before editing handlers, schemas, contracts, or shared API helpers. Use
impact route or impact tool when the route/tool is the change target and you need the generic impact report shape.
- Validate with focused backend tests and Web contract/client tests when consumers are affected.
- Run
detect-changes --scope all before commit.
Evidence To Record
- Route/tool selector used and whether it was ambiguous.
- Handler file, handler-file summary, symbol tree/dependency counts, unresolved handler-file sites, consumer count, middleware, flow count, linked tests, and shape-check mismatches.
- API impact risk and affected App Layers/Functional Areas.
- Contract or generated-client validation commands.
Current Limitations
API-surface graph quality depends on route/tool extraction and source-site resolution. If a route or tool is missing, record it as graph-quality evidence and verify source manually before concluding the API does not exist.
1---2name: api-surface3description: Use when the user asks to inspect API or MCP surfaces.4---56# API Surface With Anvien78Use this skill for route handlers, MCP/RPC tool handlers, generated contracts, response shape drift, route consumers, and API-impact decisions.910This skill is a workflow gate for API-surface work. It is not a command router. When a concrete Anvien command is needed, choose it directly from the generated Command Selection Guide.1112## Command Choices1314| Need | CLI | MCP |15|---|---|---|16| Route handlers, consumers, middleware, flows | `anvien api route-map [route] --repo <repo> --json` | `route_map` |17| MCP/tool definitions and linked flows | `anvien api tool-map [tool] --repo <repo> --json` | `tool_map` |18| Response shape drift against consumers | `anvien api shape-check [route] --repo <repo> --json` | `shape_check` |19| Route/API blast radius | `anvien api impact [route] --repo <repo> --json` | `api_impact` |20| Route impact via generic impact | `anvien impact route <route> --repo <repo> --json` | `impact` with `target_type=route` |21| MCP tool impact via generic impact | `anvien impact tool <tool> --repo <repo> --json` | `impact` with `target_type=tool` |22| Exact handler file context | `anvien context file <path> --repo <repo>` | `context` with `target_type=file` |23| Exact handler symbol context | `anvien context symbol "<handler>" --repo <repo>` | `context` with `target_type=symbol` |24| Broad API discovery | `anvien query api "<concept>" --repo <repo>` | `query` with `target_type=api` |2526MCP tool names use underscores: `route_map`, `tool_map`, `shape_check`, `api_impact`. CLI commands use hyphenated subcommands under `anvien api`. Do not invent CLI commands by reusing MCP underscore names as top-level Anvien commands.2728## Workflow29301. Refresh the graph with `anvien analyze --force` before graph-based API work.312. Use `query api` for broad route/tool discovery only when the exact route or tool is unknown.323. Use route-map/tool-map to find handlers, consumers, flows, and handler-file `handlerFile` projection data.334. Open handler files with `context file` when you need symbol tree, file dependencies, linked tests, or unresolved handler-file sites.345. Use shape-check before changing response contracts or generated Web contracts.356. Use API impact before editing handlers, schemas, contracts, or shared API helpers. Use `impact route` or `impact tool` when the route/tool is the change target and you need the generic impact report shape.367. Validate with focused backend tests and Web contract/client tests when consumers are affected.378. Run `detect-changes --scope all` before commit.3839## Evidence To Record4041- Route/tool selector used and whether it was ambiguous.42- Handler file, handler-file summary, symbol tree/dependency counts, unresolved handler-file sites, consumer count, middleware, flow count, linked tests, and shape-check mismatches.43- API impact risk and affected App Layers/Functional Areas.44- Contract or generated-client validation commands.4546## Current Limitations4748API-surface graph quality depends on route/tool extraction and source-site resolution. If a route or tool is missing, record it as graph-quality evidence and verify source manually before concluding the API does not exist.
tamnguyendinh