「filetree」给 Claude Code 维护 FILETREE.md：用文件索引减少反复读仓库的 token 浪费

filetree 是一个 Claude Code 插件，用来维护仓库里的 FILETREE.md。它给每个文件写一行用途说明，再附上内容 hash，让 AI 进入项目时先读一个轻量索引，而不是每次都从 ls、grep、打开文件、再继续摸索开始。

这个思路很朴素，但击中的痛点很准：代码库结构本身是一种上下文资产。如果每个新 session 都重新发现一遍，既浪费 token，也浪费注意力。filetree 把这部分“仓库地形图”固化成一个可提交到 git 的 Markdown 文件，团队里的其他人和后续会话都能复用。

用 hash 解决说明文档过期的问题

普通的目录说明最麻烦的是会悄悄过期。filetree 的做法是每条记录带一个 8 位内容 hash，来自 git hash-object。文件变了，hash 对不上，就能明确知道这条摘要需要检查，而不是靠人猜。

它的更新流程也很克制：/filetree:init 从零生成索引，/filetree:update 根据 added、changed、removed、renamed 同步当前仓库，/filetree:lint 做只读漂移检查并可用于 CI。所有命令都不会自动提交 FILETREE.md，最终 diff 仍然留给人审。

UNCHANGED 是省 token 的关键

README 里有个很有意思的设计叫 UNCHANGED bias。很多文件变更只是格式化、注释、小修 bug 或局部重构，文件“职责”并没有改变。遇到这类 changed 文件时，LLM 可以只输出 UNCHANGED，脚本就刷新 hash、保留旧摘要。作者估算这种路径比重写描述便宜得多，也更符合真实开发中的变更分布。

它没有引入数据库、守护进程、watcher 或向量索引，依赖也很轻：运行期需要 git，Python 版本要求 3.9 以上，脚本使用标准库。插件版本目前是 0.2.0，协议在 plugin manifest 中标为 MIT。

如果你经常让 Claude Code 接手一个中大型仓库，filetree 适合当作项目入口文件来用。把 FILETREE.md 接进 CLAUDE.md 或 AGENTS.md，让代理在定位实现前先读它，很多“先看一圈目录”的成本就可以被摊薄到一次维护里。