HelloAGENTS 项目知识库实战:.helloagents 目录如何让 Agent 跨会话记住项目
HelloAGENTS 项目知识库实战:.helloagents 目录如何让 Agent 跨会话记住项目
用 AI 写代码最让人抓狂的一点,是它经常"转头就忘"。你刚纠正过的命名习惯、上周踩过的坑、项目的技术栈和验证命令,每次新开会话都要从头再讲一遍。HelloAGENTS 用一个项目级的 .helloagents/ 目录解决了这个问题:它把项目知识库、方案包和会话恢复状态都落到磁盘上,让 Agent 跨会话、跨工作区都能"记住"项目,不用反复重新理解同一批事实。
本文带你从零看懂这个目录的每个文件,以及它如何把 Agent 从"健忘实习生"变成"熟悉项目的老成员"。
为什么 Agent 总是"失忆"?
没有持久化时,Agent 的所有"记忆"都活在聊天窗口里。窗口一关、会话一切换,项目上下文就清零:
- 反复解释:技术栈、架构、模块划分每次都要重新描述。
- 约定丢失:命名规范、提交格式、测试要求等"从代码看不出来的约定"无处安放。
- 状态断裂:长任务做到一半中断,恢复时 Agent 不知道上一步做到哪、下一步该干什么。
- 重复踩坑:上次调试发现的坑,这次又会原样踩一遍。
HelloAGENTS 的思路是:把"应该记住的东西"从对话里挪到 .helloagents/ 目录,形成一份可被后续会话随时读取的项目知识库。下图对比了同一任务在有无 HelloAGENTS 加持下的交付效果——接入后,Agent 能按项目已有的设计规范完整实现,而不是各写各的。
而没有任何项目记忆时,交付结果往往缺失、风格不一致,需要人工反复补刀:
.helloagents 目录结构全解
~init 会在项目根目录生成 .helloagents/,它是项目本地知识、方案、状态和运行态的统一存放地。一个初始化后的目录大致长这样:
.helloagents/
├── context.md # 项目概述、技术栈、架构、模块索引
├── guidelines.md # 从代码看不出来的编码约定
├── verify.yaml # 验证命令(lint / test / build)
├── DESIGN.md # UI 设计契约(有界面时生成)
├── CHANGELOG.md # 项目级变更历史
├── modules/ # 每个模块的经验笔记
│ └── xxx.md
├── plans/ # 进行中的方案包
│ └── <feature>/
├── archive/ # 已归档的方案包
└── sessions/ # 会话恢复状态与证据
└── <workspace>/<session>/
├── STATE.md
├── runtime.json
├── active.json
└── artifacts/ # 结构化交付证据
你可以把它分成三层来理解:知识库(长期、稳定,给人和 Agent 共享)、方案包(一次复杂任务的拆解)、会话运行态(短期、可恢复,含过期自动清理)。
一键初始化:~init 如何生成知识库
你不需要手写这些文件。在 AI CLI 的聊天框里输入:
~init
HelloAGENTS 会分析代码库后,按官方模板自动生成并填充知识库文件,为受支持的宿主写入项目级完整规则标记,并把 .helloagents/ 追加进 .gitignore。整个过程是幂等的——重复执行是安全的,缺失的文件会补全,已存在的文件按模板增量更新,不会自由改写你的结构。
这套生成逻辑由 skills/commands/init/SKILL.md 定义,所有文件都对应 templates/ 目录下的一份模板。空项目会先保留目录骨架,等首次编码任务时再补全知识文件。
知识库文件逐个看懂
下面这几个文件,是 Agent"记住项目"的核心载体。
context.md — 项目的自我介绍
对应 templates/context.md,记录项目做什么、用什么技术栈、架构如何、关键目录各自负责什么,并链接到 modules/ 下各模块文档。Agent 新会话一读它就"入坑"。
guidelines.md — 那些代码看不出来的约定
对应 templates/guidelines.md。命名规范、Git 工作流、测试要求里"非显而易见的部分"都写在这里。模板里特意强调:能从代码推断的风格不必写,只记 AI 猜不到的约定。
verify.yaml — 验证命令清单
对应 templates/verify.yaml。质量闭环(~qa)会优先从这里读取 lint / test / build 命令,而不是每次现猜。检测顺序是:.helloagents/verify.yaml → 包管理器脚本 → 自动探测。
DESIGN.md — 设计契约
对应 templates/DESIGN.md。当项目有 UI 时生成,沉淀设计 token、组件与模式、状态覆盖、无障碍要求、禁止事项等。UI 工作的约束优先级固定为:当前 plan.md / PRD 决策 → DESIGN.md → 已加载的 hello-ui 规则,保证界面风格跨会话一致。
modules/*.md — 模块经验笔记
对应 templates/modules/module.md。每个关键模块一份,记录用途、关键文件、依赖,以及最重要的"经验"章节——调试发现、架构决策、踩坑记录,增量追加、不重写。
CHANGELOG.md — 变更历史
对应 templates/CHANGELOG.md,维护项目级变更日志,让后续会话能快速感知"最近改了什么"。
会话恢复:STATE.md 与 sessions 目录
知识库管"长期记忆",sessions/ 则管"这次任务做到哪了"。HelloAGENTS 把状态文件放在按工作区和会话隔离的路径下,例如 .helloagents/sessions/<workspace>/<session>/STATE.md,其中 <workspace> 通常就是当前 Git 分支。
templates/STATE.md 是一份简洁的恢复快照,只记几样东西:主线目标、正在做什么、关键上下文、下一步具体动作、阻塞项。它不是全对话的万能记忆,而是让中断后的会话能精准续跑。同一 CLI 会话会稳定落在同一个目录里,/resume 时可直接复用;短期运行态和证据默认 72 小时后过期清理,避免目录越堆越乱。
这套会话作用域与存储路径的解析逻辑,核心实现在 scripts/project-storage.mjs 里,它会根据项目是否初始化、是否为 Git 仓库、是否多工作树等条件,动态决定状态和证据落盘到哪里。
经验沉淀:hello-reflect 让踩坑不再重演
知识库不只是"读",还会"长"。skills/hello-reflect/SKILL.md 定义了会话反思机制:当一次任务经历了多次验证循环才通过、调试超过几次才修复、方案中途变更、或你纠正了 Agent 的错误假设时,Agent 会把这些发现提炼成抽象的经验教训,追加到对应 modules/*.md 的"经验"章节,或写入 context.md 末尾。
要求很克制:每条经验不超过两行,必须是可指导方向的抽象结论而非具体代码模板,不记录显而易见的事。正是这种"只留真正有价值的发现"的纪律,让知识库随使用越来越懂你的项目,而不是越积越杂。
整体技能调度、质量三重保障和流程纪律,由 skills/helloagents/SKILL.md 统一约束,确保"读取知识库"和"回写经验"发生在正确的阶段。
进阶:repo-shared 共享知识库
默认情况下,知识就存在项目本地的 .helloagents/ 里。当你在 ~/.helloagents/helloagents.json 中把 project_store_mode 设为 "repo-shared" 时,稳定的知识文件(context.md、guidelines.md、DESIGN.md、verify.yaml、modules/、plans/、archive/)会集中存到 ~/.helloagents/projects/<repo-key>/,多个 worktree 可以共享同一份知识;而会话状态和证据仍留在各自的工作项目里,互不干扰。这对"同一个仓库、多个分支/工作目录并行开发"的团队特别友好。
上手三步与最佳实践
- 装好后初始化:在项目里输入
~init,一次性生成.helloagents/知识库骨架。 - 让知识跟着任务长:日常用
~commit、~qa收尾,配合kb_create_mode让知识库在编码任务中自动同步。 - 定期
~clean:归档已完成的方案包、清理临时运行态,保持目录清爽。
三条小贴士:把"代码猜不出来的约定"写进 guidelines.md 收益最大;有界面的项目务必维护好 DESIGN.md,它能显著提升跨会话的视觉一致性;经验章节坚持"增量追加、抽象表达",避免知识库退化成流水账。
小结:
.helloagents/是 HelloAGENTS 的"项目记忆中枢"。context.md讲清项目是什么,guidelines.md记牢约定,verify.yaml锁定验证方式,modules/沉淀踩坑经验,sessions/负责断点续跑。把它用起来,Agent 就不再是每次都要从零开始的新人,而是一位真正熟悉你项目的长期伙伴。

