c3-query

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

C3 Query - Architecture Navigation

C3 Query - 架构导航

Navigate C3 docs AND explore corresponding code. Full context = docs + code.

Relationship to c3-navigator agent: This skill defines the query workflow. The

c3-navigator

agent implements this workflow. Use the agent when spawning via Task tool; use this skill directly for inline execution.

浏览C3文档并探索对应代码。完整上下文 = 文档 + 代码。

与c3-navigator agent的关系： 本技能定义了查询工作流。

c3-navigator

agent负责实现该工作流。通过Task工具调用时使用该agent；直接内联执行时使用本技能。

Precondition: C3 Adopted

前置条件：已采用C3

Run

npx -y @lagz0ne/c3x list --json

via Bash. If it fails or returns empty, STOP.

If missing:

This project doesn't have C3 docs yet. Use the c3-onboard skill to create documentation first.

Do NOT proceed until topology is confirmed.

通过Bash执行

npx -y @lagz0ne/c3x list --json

命令。如果执行失败或返回空结果，请停止操作。

如果未找到相关内容：

该项目尚未配置C3文档。请先使用c3-onboard技能创建文档。

在确认拓扑结构前，请勿继续操作。

REQUIRED: Load References

必填步骤：加载参考资料

Before proceeding, Read these files (relative to this skill's directory):

```
references/skill-harness.md
```
- Red flags and complexity rules
```
references/layer-navigation.md
```
- How to traverse C3 docs
```
references/constraint-chain.md
```
- Constraint chain query procedure (for "what constraints apply to X")

在继续操作前，请阅读以下文件（相对于本技能的目录）：

```
references/skill-harness.md
```
- 警示标识与复杂度规则
```
references/layer-navigation.md
```
- C3文档遍历方法
```
references/constraint-chain.md
```
- 约束链查询流程（适用于“X需遵循哪些约束”类问题）

Query Flow

查询工作流

Query → Load Topology (CLI) → Clarify Intent → Navigate Layers → Extract References → Explore Code
                                     │
                                     └── Use AskUserQuestion if ambiguous

Query → Load Topology (CLI) → Clarify Intent → Navigate Layers → Extract References → Explore Code
                                     │
                                     └── Use AskUserQuestion if ambiguous

Progress Checklist

进度检查清单

Query Progress:
- [ ] Step 0a: Topology loaded via `npx -y @lagz0ne/c3x list --json`
- [ ] Step 0b: Intent clarified (or skipped if specific)
- [ ] Step 1: Context navigated (found relevant container/component from JSON)
- [ ] Step 2: References extracted (code paths, symbols — Read docs for body content)
- [ ] Step 3: Code explored (verified against docs)
- [ ] Response delivered with layer, refs, insights

Query Progress:
- [ ] Step 0a: Topology loaded via `npx -y @lagz0ne/c3x list --json`
- [ ] Step 0b: Intent clarified (or skipped if specific)
- [ ] Step 1: Context navigated (found relevant container/component from JSON)
- [ ] Step 2: References extracted (code paths, symbols — Read docs for body content)
- [ ] Step 3: Code explored (verified against docs)
- [ ] Response delivered with layer, refs, insights

Step 0a: Load Topology

步骤0a：加载拓扑结构

FIRST action: Run

npx -y @lagz0ne/c3x list --json

via Bash to load full topology.

bash

npx -y @lagz0ne/c3x list --json

The JSON output contains every entity's id, type, title, path, relationships, and frontmatter. Use this to:

Identify which containers, components, refs, and ADRs exist
Match the user's query to relevant entities by title, type, or relationship
Resolve C3 IDs (c3-N, c3-NNN, adr-, ref-) to file paths

Do NOT manually Glob or Read

.c3/

directory listings. The JSON has everything needed for discovery.

Only use the Read tool after you've identified specific entities from the JSON — and only when you need body content (prose, Code References sections, edge cases) that isn't in the frontmatter.

首要操作： 通过Bash执行

npx -y @lagz0ne/c3x list --json

命令以加载完整拓扑结构。

bash

npx -y @lagz0ne/c3x list --json

JSON输出包含每个实体的id、类型、标题、路径、关联关系和前置元数据。可用于：

确认存在的容器、组件、refs和ADR
通过标题、类型或关联关系将用户查询与相关实体匹配
将C3 ID（c3-N、c3-NNN、adr-、ref-）解析为文件路径

请勿手动通过Glob或Read操作

.c3/

目录列表。JSON中包含了所有发现所需的信息。

仅在从JSON中确定了具体实体后，且需要获取前置元数据中未包含的正文内容（描述性文字、Code References章节、边缘情况）时，才使用Read工具。

Step 0b: Clarify Intent

步骤0b：明确用户意图

Ask when:

Query vague ("how does X work?" - which aspect?)
Multiple interpretations ("authentication" - login? tokens? sessions?)
Scope unclear ("frontend" - whole container or specific component?)

Skip when:

Query includes C3 ID (c3-102)
Query specific ("where is login form submitted?")
User says "show me everything about X"

需询问的情况：

查询内容模糊（例如“X如何工作？”——具体指哪个方面？）
存在多种解读（例如“身份验证”——登录？令牌？会话？）
范围不明确（例如“前端”——整个容器还是特定组件？）

可跳过的情况：

查询中包含C3 ID（如c3-102）
查询内容具体（例如“登录表单提交到哪里？”）
用户要求“展示关于X的所有信息”

Step 1: Navigate Layers

步骤1：遍历层级

Use the JSON topology from Step 0a to navigate: Context → Container → Component

Match from JSON — Find relevant entities by title, type, or relationships in the JSON output
Read for depth — Only Read entity files when you need body content (prose,
```
## Code References
```
, edge cases) not available in the JSON frontmatter

Doc Section	Extract For Code
Component name	Class/module names
`## Code References`	Direct file paths, symbols
Technology	Framework patterns
Entry points	Main files, handlers

使用步骤0a中获取的JSON拓扑结构进行遍历：上下文 → 容器 → 组件

从JSON中匹配 — 通过JSON输出中的标题、类型或关联关系找到相关实体
读取以获取深度信息 — 仅当需要获取JSON前置元数据中未包含的正文内容（描述性文字、
```
## Code References
```
章节、边缘情况）时，才读取实体文件

文档章节	提取用于代码探索的信息
组件名称	类/模块名称
`## Code References`	直接文件路径、符号
技术栈	框架模式
入口点	主文件、处理器

Step 2: Extract References

步骤2：提取参考信息

From the identified component(s), extract:

File paths from
```
## Code References
```
Related patterns from
```
## Related Refs
```

从已识别的组件中提取：

```
## Code References
```
中的文件路径
```
## Related Refs
```
中的相关模式

Reference Lookup

参考信息查找

If query relates to patterns/conventions:

Find matching
```
ref-*
```
entities from the JSON topology (loaded in Step 0a)
Read ref file for body content, return ref content + citing components

如果查询涉及模式/约定：

从步骤0a加载的JSON拓扑结构中找到匹配的
```
ref-*
```
实体
读取ref文件的正文内容，返回ref内容及引用该ref的组件

Step 3: Explore Code

步骤3：探索代码

Use extracted references:

Glob:
```
src/auth/**/*.ts
```
Grep: Class names, functions
Read: Specific files from
```
## Code References
```

使用提取的参考信息：

Glob：
```
src/auth/**/*.ts
```
Grep：类名、函数
Read：
```
## Code References
```
中的特定文件

Query Types

查询类型

Type	User Says	Response
Docs	"where is X", "explain X"	Docs + suggest code exploration
Code	"show me code for X"	Full flow through code
Deep	"explore X thoroughly"	Docs + Code + Related
Constraints	"what rules/constraints apply to X"	Full constraint chain

类型	用户提问示例	响应内容
文档类	“X在哪里”、“解释X”	文档内容 + 建议代码探索
代码类	“展示X的代码”	完整代码流程
深度类	“全面探索X”	文档 + 代码 + 相关内容
约束类	“X需遵循哪些规则/约束”	完整约束链

Constraint Chain Query

约束链查询

For constraint queries ("what constraints apply to X?"), follow the procedure in

references/constraint-chain.md

. Read upward through the hierarchy, collect cited refs, and synthesize the full constraint chain.

对于约束类查询（例如“X需遵循哪些约束？”），请遵循

references/constraint-chain.md

中的流程。向上遍历层级结构，收集引用的refs，然后合成完整的约束链。

Edge Cases

边缘情况

Situation	Action
Topic not in C3 docs	Search code directly, suggest documenting if significant
Spans multiple containers	List all affected containers, explain relationships
Docs seem stale	Note discrepancy, suggest running c3-audit or c3-change skill to fix

场景	操作
主题未在C3文档中提及	直接搜索代码，若内容重要则建议添加文档
涉及多个容器	列出所有受影响的容器，解释其关联关系
文档似乎已过时	记录差异，建议运行c3-audit或c3-change技能进行修复

Examples

示例

Example 1: Component lookup

User: "Where is authentication handled?"

Step 0a: Run `npx -y @lagz0ne/c3x list --json` → JSON shows c3-2-api container, c3-201-auth-middleware component with title "Auth Middleware"
Step 1: Match "authentication" → c3-201-auth-middleware (from JSON relationships + title)
Step 2: Read .c3/c3-2-api/c3-201-auth-middleware.md → Get code refs (need body content)

Response:
**Layer:** c3-201 (Auth Middleware)

Authentication is handled by the AuthMiddleware component in the API container.

**Code References:**
- `src/api/middleware/auth.ts` - JWT validation
- `src/api/middleware/session.ts` - Session management

**Key Insights:**
Uses RS256 for JWT signing. Sessions stored in Redis.

**Related:** See c3-202-user-service for user lookup

Example 2: Pattern lookup

User: "How does error handling work?"

Step 0a: Run `npx -y @lagz0ne/c3x list --json` → JSON shows ref-error-handling entity, cited by c3-201, c3-203, c3-205
Step 1: Match "error handling" → ref-error-handling (from JSON title + relationships)

Response:
**Pattern:** ref-error-handling

Error handling follows a centralized pattern documented in refs.

**Pattern Summary:**
- All errors extend BaseError class
- HTTP errors map to status codes via errorToStatus()
- Logged with correlation ID

**Used By:** c3-201, c3-203, c3-205

示例1：组件查找

User: "Where is authentication handled?"

Step 0a: Run `npx -y @lagz0ne/c3x list --json` → JSON shows c3-2-api container, c3-201-auth-middleware component with title "Auth Middleware"
Step 1: Match "authentication" → c3-201-auth-middleware (from JSON relationships + title)
Step 2: Read .c3/c3-2-api/c3-201-auth-middleware.md → Get code refs (need body content)

响应： 层级： c3-201（Auth Middleware）

身份验证由API容器中的AuthMiddleware组件负责处理。

代码参考：

```
src/api/middleware/auth.ts
```
- JWT验证
```
src/api/middleware/session.ts
```
- 会话管理

关键要点： 使用RS256算法进行JWT签名。会话存储在Redis中。

相关内容： 查看c3-202-user-service了解用户查找逻辑

示例2：模式查找

User: "How does error handling work?"

Step 0a: Run `npx -y @lagz0ne/c3x list --json` → JSON shows ref-error-handling entity, cited by c3-201, c3-203, c3-205
Step 1: Match "error handling" → ref-error-handling (from JSON title + relationships)

响应： 模式： ref-error-handling

错误处理遵循refs中记录的集中式模式。

模式摘要：

所有错误均继承自BaseError类
HTTP错误通过errorToStatus()映射为状态码
附带关联ID进行日志记录

使用该模式的组件： c3-201、c3-203、c3-205

Response Format

响应格式

**Layer:** <c3-id> (<name>)

<Architecture from docs>

**Code References:**
- `path/file.ts` - <role>

**Key Insights:**
<Observations from code>

**Related:** <navigation hints>

For constraint chain queries, use the response format in

references/constraint-chain.md

instead.

**Layer:** <c3-id> (<name>)

<Architecture from docs>

**Code References:**
- `path/file.ts` - <role>

**Key Insights:**
<Observations from code>

**Related:** <navigation hints>

对于约束链查询，请改用

references/constraint-chain.md

中定义的响应格式。