intent-layer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Intent Layer

意图层

Hierarchical AGENTS.md infrastructure so agents navigate codebases like senior engineers.

为Agent构建分层AGENTS.md基础设施，使其能够像资深工程师一样导航代码库。

Core Principle

核心原则

Only ONE root context file. CLAUDE.md and AGENTS.md should NOT coexist at project root. Child AGENTS.md in subdirectories are encouraged for complex subsystems.

仅保留一个根上下文文件。项目根目录下不能同时存在CLAUDE.md和AGENTS.md。对于复杂的子系统，建议在子目录中创建子级AGENTS.md文件。

Workflow

工作流程

1. Detect state
   scripts/detect_state.sh /path/to/project
   → Returns: none | partial | complete

2. Route
   none/partial → Initial setup (steps 3-5)
   complete     → Maintenance (step 6)

3. Measure [gate - show table first]
   scripts/analyze_structure.sh /path/to/project
   scripts/estimate_tokens.sh /path/to/each/source/dir

4. Decide
   No root file  → Ask: CLAUDE.md or AGENTS.md?
   Has root file → Add Intent Layer section + child nodes if needed

5. Execute
   Use references/templates.md for structure
   Use references/node-examples.md for real-world patterns
   Validate: one root, READ-FIRST directive, <4k tokens per node

6. Maintenance mode (when state=complete)
   Ask user:
   a) Audit nodes     → Use references/capture-protocol.md for SME questions
   b) Find candidates → Re-measure tokens, suggest new nodes
   c) Both

1. 检测状态
   scripts/detect_state.sh /path/to/project
   → 返回结果：none | partial | complete

2. 路由
   none/partial → 初始设置（步骤3-5）
   complete     → 维护（步骤6）

3. 评估 [关卡 - 先展示表格]
   scripts/analyze_structure.sh /path/to/project
   scripts/estimate_tokens.sh /path/to/each/source/dir

4. 决策
   无根文件 → 询问：创建CLAUDE.md还是AGENTS.md？
   已有根文件 → 添加意图层章节 + 必要的子节点

5. 执行
   使用references/templates.md中的结构模板
   使用references/node-examples.md中的真实场景模式
   验证：仅一个根文件、包含READ-FIRST指令、每个节点的token数<4k

6. 维护模式（当状态=complete时）
   询问用户：
   a) 审核节点 → 使用references/capture-protocol.md中的专家访谈问题
   b) 寻找候选节点 → 重新评估token数，建议新节点
   c) 同时进行a和b

When to Create Child Nodes

何时创建子节点

Signal	Action
>20k tokens in directory	Create AGENTS.md
Responsibility shift	Create AGENTS.md
Hidden contracts/invariants	Document in nearest ancestor
Cross-cutting concern	Place at LCA

Do NOT create for: every directory, simple utilities, test folders (unless complex).

信号	操作
目录中token数>20k	创建AGENTS.md
职责转移	创建AGENTS.md
存在隐藏约定/不变量	在最近的父节点中记录
跨领域关注点	放置在最近公共祖先（LCA）节点

请勿为以下场景创建子节点：每个目录都创建、简单工具、测试文件夹（除非测试逻辑复杂）。

Capture Questions

采集问题

When documenting existing code, ask:

What does this area own? What's out of scope?
What invariants must never be violated?
What repeatedly confuses new engineers?
What patterns should always be followed?

在记录现有代码时，询问以下问题：

该模块负责什么？哪些内容不在其职责范围内？
哪些不变量绝对不能被破坏？
哪些内容经常让新工程师感到困惑？
应该始终遵循哪些模式？

Resources

资源

Scripts:

```
scripts/detect_state.sh
```
- Check Intent Layer state (none/partial/complete)
```
scripts/analyze_structure.sh
```
- Find semantic boundaries
```
scripts/estimate_tokens.sh
```
- Measure directory complexity

References:

```
references/templates.md
```
- Root and child node templates
```
references/node-examples.md
```
- Real-world examples
```
references/capture-protocol.md
```
- SME interview protocol

脚本：

```
scripts/detect_state.sh
```
- 检测意图层状态（none/partial/complete）
```
scripts/analyze_structure.sh
```
- 识别语义边界
```
scripts/estimate_tokens.sh
```
- 评估目录复杂度

参考资料：

```
references/templates.md
```
- 根节点和子节点模板
```
references/node-examples.md
```
- 真实场景示例
```
references/capture-protocol.md
```
- 专家访谈协议