intent-layer

用途

Intent Layer 用于为代码库搭建分层式的 Intent Layer 基础设施，即一组 AGENTS.md 文件。其目标是让 AI 智能体能够像资深工程师一样在代码库中导航与理解上下文。适用于初始化新项目、为现有仓库添加 context 基础设施，以及在项目完成后进行维护。

核心原则

• 只保留一个根上下文文件。CLAUDE.md 和 AGENTS.md 不应在项目根目录同时存在。
• 鼓励在复杂子目录中创建子 AGENTS.md，用于描述子系统。

主要能力与工作流程

工作流按以下步骤进行：

1. 检测状态 运行 scripts/detect_state.sh /path/to/project，返回 none、partial 或 complete 三种状态。

2. 路由

   • none 或 partial：进入初始设置（步骤 3 至 5）
   • complete：进入维护模式（步骤 6）

3. 度量（gate，先展示表格） 运行 scripts/analyze_structure.sh /path/to/project 以及 scripts/estimate_tokens.sh /path/to/each/source/dir。

4. 决策

   • 没有根文件：询问使用 CLAUDE.md 还是 AGENTS.md。
   • 已有根文件：添加 Intent Layer 章节，并在需要时添加子节点。

5. 执行

   • 使用 references/templates.md 了解结构。
   • 使用 references/node-examples.md 了解真实模式。
   • 验证：一个根文件、READ-FIRST 指令、每个节点小于 4k tokens。

6. 维护模式（当状态为 complete） 询问用户选择：a) 审计节点，使用 references/capture-protocol.md 中的 SME 问题进行；b) 查找候选节点，重新测量 tokens 并建议新节点；c) 两者都做。

何时创建子节点

依据以下信号决定是否创建子节点：

• 目录超过 20k tokens：创建 AGENTS.md
• 职责发生转移：创建 AGENTS.md
• 存在隐藏契约或不变量：记录在最近的祖先节点中
• 跨领域关注点：放置在 LCA（最低共同祖先）处

不应创建子节点的情况：每个目录、简单工具、测试文件夹（除非复杂）。

捕获问题

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

1. 该区域负责什么？什么超出范围？
2. 哪些不变量绝不能违反？
3. 什么反复让新工程师困惑？
4. 应始终遵循哪些模式？

资源

脚本：

• scripts/detect_state.sh - 检查 Intent Layer 状态（none/partial/complete）
• scripts/analyze_structure.sh - 查找语义边界
• scripts/estimate_tokens.sh - 测量目录复杂度

参考资料：

• references/templates.md - 根节点与子节点模板
• references/node-examples.md - 真实示例
• references/capture-protocol.md - SME 访谈协议

限制

关于该工具是否收费、支持的平台、具体版本要求等信息暂未提供。