ql-link/linkrag/agents-tree-sync

AGENTS Tree Sync

目标

保持根目录 AGENTS.md 中的“当前项目结构”树与仓库源码、脚本、配置、测试、Agent/Skill 等非 docs 核心结构一致。

docs/ 是研发文档沉淀目录。docs/ 下任何文件或目录结构变化，都不要求、也不允许因此同步更新 AGENTS.md。

触发规则

在以下情况必须同步更新 AGENTS.md：

1. 在 src/、scripts/、tests/、.ai/skills/ 等非 docs/ 目录新增目录或核心文件
2. 在非 docs/ 目录删除目录或核心文件
3. 在非 docs/ 目录移动或重命名目录/文件
4. 调整非 docs/ 目录职责，导致树上的注释不再准确

如果只是修改文件内容、没有改变结构，一般不需要更新这棵树。

以下情况不触发本 skill：

1. docs/ 下新增、删除、移动、重命名任何文件
2. docs/ 下新增、删除、移动、重命名任何目录
3. .specs/ 下任何 feature 临时目录的变化（整目录 git-ignored）
4. docs/ 下文档内容修改
5. 仅因 docs/ 结构与 AGENTS.md 中展示不一致而想同步目录树

更新范围

AGENTS.md 中的树只维护：

• 整体目录骨架
• 核心文件
• 必要的简短注释

不要把它扩展成完整文件清单。保持“骨架 + 关键入口”的粒度。

同步步骤

1. 完成文件/目录变更后，重新检查当前仓库结构。
2. 对照 AGENTS.md 中的树，删除失效节点。
3. 补充新增节点，保持现有缩进和树形符号风格一致。
4. 如果目录职责发生变化，同时修正行尾注释。
5. 在最终回复中明确说明：已同步更新 AGENTS.md 目录树。

约束

• 不要为了“绝对完整”把所有测试文件、临时文件、IDE 文件都列出来。
• 不要因为 docs/ 目录下任何文件或目录结构变化而同步更新 AGENTS.md。
• 即使用户在 .specs/ 下新增、删除、移动或重命名任何 feature 工作目录，也不要同步更新 AGENTS.md。
• 继续省略 .git、.venv、.pytest_cache、__pycache__ 等运行时或缓存目录。
• 优先保留用户当前已经确认过的展示风格，只做最小必要修改。
• 如果用户明确要求“不要更新 AGENTS.md”，则遵从用户要求。