1. 项目概述一个为AI智能体设计的结构化知识库如果你和我一样每天都在和各种AI编程助手打交道——Claude Code、Cursor、Windsurf或者Aider——那你肯定也经历过这种挫败感每次打开一个新会话就像面对一个失忆的同事。你得从头到尾把项目背景、客户信息、上次做到哪一步、甚至你的个人工作习惯再复述一遍。这种重复的“上下文对齐”工作不仅浪费时间更打断了深度工作的心流。我过去几个月一直在寻找一种方法能让这些AI助手在不同会话间“记住”事情直到我遇到了Scott Heffield的“Results Studio”模板并在此基础上打磨出了一套自己的实战工作流。简单来说这是一个基于文件系统的个人知识库模板它不依赖任何特定的笔记软件或复杂工具核心就是一套文件夹结构、几个Markdown文件约定以及一个关键理念将机器可读的上下文AGENTS.md和人可读的进度HUMAN.md放在工作发生的文件夹旁边。AI智能体在会话开始时读取这些文件就能立刻进入状态省去了你90%的口头简报时间。它借鉴了Tiago Forte的PARA方法项目、领域、资源、归档来组织信息但真正让它发光的是那些专门写给AI看的“说明书”。这个方案的精妙之处在于它的极简和普适性。它不绑定任何专有平台就是纯文本文件你可以放在Google Drive、OneDrive同步或者直接用Git管理。这意味着无论你换用哪个AI工具只要它支持读取项目根目录的特定文件现在主流工具基本都支持你的工作上下文就能无缝迁移。接下来我会带你从零开始搭建、个性化并分享我在实际咨询和开发工作中使用它时积累的一系列实战技巧和避坑指南。2. 核心设计思路与工作原理解析2.1 解决AI智能体的“失忆症”问题现代AI编码助手本质上是“无状态”的。每次会话都是一个全新的开始模型没有长期记忆。虽然有些工具提供了有限的“会话记忆”功能但一旦关闭窗口或切换项目这些记忆就消失了。传统的解决方案是每次都在提示词里塞进大段的上下文但这不仅低效而且受限于模型的上下文窗口长度。Results Studio模板的解决方案异常直接既然AI可以读取文件那就把需要记忆的上下文写成文件放在它一定能看到的地方。这个设计基于一个观察大多数AI智能体在启动时都会自动扫描项目根目录下像AGENTS.md、README.md这样的文件来获取项目上下文。模板正是标准化并最大化利用了这一点。核心文件角色解析AGENTS.md这是给AI看的“任务简报”。它用清晰、结构化的语言告诉AI这个项目是什么、当前目标、技术栈、约束条件、下一步行动是什么。它的语言是指令式的旨在消除歧义。HUMAN.md这是给你自己看的“进度看板”。它用更随意、笔记式的语言记录会议要点、临时决定、待办事项、联系人信息。AI也能读它并从中提取信息来更新AGENTS.md但它的首要服务对象是人。根目录的HUMAN.md这是一个总览仪表盘。它汇总了所有活跃项目02-projects/和领域03-areas/中的关键信息比如即将到期的任务、活跃项目状态、待开发的商机等。每天开始工作前你或让AI读一下这个文件就能快速掌握全局。这种分离是关键。AGENTS.md保持精简、客观、面向行动便于AI快速理解HUMAN.md则可以容纳更多杂乱、主观、过程性的笔记。两者结合既保证了AI的效率也保留了人类思考的灵活性。2.2 PARA方法在AI协作场景下的重塑PARA方法Projects, Areas, Resources, Archive是一个久经考验的信息组织框架。Results Studio模板继承了这一结构但为其注入了AI协作的基因。项目Projects位于02-projects/。每个项目都是一个有明确终点的任务例如“为Client X开发APIv2”、“撰写Q3市场报告”。每个项目文件夹内都必然包含AGENTS.md和HUMAN.md。这是你与AI协作的主战场。领域Areas位于03-areas/。代表你持续关注的领域或职责没有明确的结束日期例如“团队基础设施”、“个人学习”、“健康”。它们同样拥有AGENTS.md和HUMAN.md用于指导AI在该领域内的长期工作。资源Resources位于04-resources/。这里是静态参考资料的仓库。模板中最重要的子文件夹是About-Me/里面的AboutMe.md是你个人的“用户手册”用于告诉AI你的技能偏好、沟通风格、常用工具链等。这是实现个性化协作的基石。归档Archive位于05-archive/。已完成的项目或不再活跃的领域移至此地。保留它们的AGENTS.md和HUMAN.md可以作为宝贵的历史记录和案例库供未来类似项目参考。收件箱Inbox位于01-inbox/。用于临时存放未处理的笔记、代码片段、想法。每天或每周需要对其进行“清空”Triage将内容归类到上述四个核心区域。这种结构的优势在于“上下文局部性”。当AI进入02-projects/Client-A-Website/文件夹工作时它只需要读取这个文件夹下的AGENTS.md和可能引用的04-resources/中的内容。它不需要加载整个知识库从而减少了无关信息的干扰也更节省上下文令牌。这种模块化设计使得知识库可以随着项目增长而无限扩展而不会降低单个会话的协作效率。3. 从零开始部署与个性化配置实战3.1 环境准备与模板获取首先你需要决定存储方案。我强烈建议使用带有本地同步功能的云盘如Google Drive桌面版、OneDrive或Dropbox。这样既能保证文件在多设备间的同步和备份又能让AI工具通过本地路径直接访问性能最好。我将我的知识库放在Google Drive/My Drive/Workspace/ai-vault/。获取模板有三种方式各有利弊Git Fork推荐给熟悉Git的用户使用gh repo fork命令可以快速创建一个属于你自己的副本并保留与原仓库的关联便于后续合并更新。# 假设已安装GitHub CLI (gh) gh repo fork scottheffield/results-studio my-ai-vault cd my-ai-vault直接克隆如果你不需要fork关联简单克隆即可。git clone https://github.com/scottheffield/results-studio.git my-ai-vault cd my-ai-vault下载ZIP最直接的方式适合不想接触命令行的用户。直接从GitHub下载ZIP包并解压到你的目标目录。重要安全提示这个知识库未来会包含你的客户信息、商业笔记和个人思考。务必将其初始化为一个私有Git仓库。如果你使用Git在第一次提交后用gh repo create --private推送到GitHub。如果使用云盘确保同步文件夹的共享设置是私有的。3.2 清理演示内容与初始化工作区模板自带了一些虚构的示例项目如“Acme Corp Website Redesign”来展示结构。在开始真实工作前需要清理它们。高效清理法使用AI助手 打开你的AI编程助手如Cursor进入知识库根目录然后输入以下提示词请帮我将此知识库重置以供我自己使用。请按顺序执行以下操作并在删除任何内容前向我确认 1. 删除 02-projects/、03-areas/、05-archive/ 目录下的所有文件夹以及 01-inbox/ 目录下除 AGENTS.md 外的所有文件。 2. 清空根目录的 HUMAN.md 文件内容但保留原有的章节标题如 ## 即将到期、## 活跃项目。 3. 将 04-resources/About-Me/ 目录下的所有文件内容替换为对应文件顶部模板说明中的空白版本。 4. 请保留根目录的 AGENTS.md、CLAUDE.md、README.md、LICENSE、.gitignore 以及 04-resources/Templates/ 目录。让AI逐步执行并确认这是一个很好的“人机协作”入门练习。手动清理法 直接通过文件管理器删除上述目录中的示例文件夹和文件即可。重点是保留04-resources/Templates/里的模板文件它们是创建新项目的蓝图。3.3 核心文件深度个性化这是让知识库真正为你工作的关键步骤直接决定了AI助手理解你的深度。1. 打造你的“用户手册”AboutMe.md打开04-resources/About-Me/AboutMe.md。不要只填写姓名职位。把它当成给一位新入职的、超级聪明的实习生写的指南。我建议包含以下维度专业背景你的核心技能栈、熟悉的语言框架、常用的开发工具。工作风格你偏好详细的方案还是快速的原型你喜欢AI主动提出方案还是等你指令代码风格要求如lint规则、注释规范。沟通偏好解释技术概念时你希望的详细程度。你希望AI如何提问例如“这里有两个方案A是…B是…我推荐A因为…”。业务上下文你所在的行业、主要客户类型、当前公司的核心产品/服务。禁忌与偏好你坚决不用的技术、你个人或公司的安全合规要求。示例片段## 沟通与协作风格 - **决策偏好**当我提出一个模糊需求时请先提供1-2个最可行的具体方案选项并附带简要的利弊分析而不是问我“你想怎么做”。例如我问“如何优化这个页面加载”你可以回答“方案A使用懒加载图片预计提升20%速度方案B代码分割提升15%但改动较大。推荐A因为成本低。” - **代码细节**所有Python代码请遵循PEP 8使用类型提示Type Hints。在复杂函数前请用三引号注释说明算法逻辑。 - **安全红线**任何涉及数据库查询的操作必须使用参数化查询绝对禁止字符串拼接。2. 定制根目录的AGENTS.md这是AI进入知识库后读的第一份“总章程”。模板提供的版本已经很好但你可以调整以更符合你的习惯。修改会话仪式模板定义了“开始会话”和“结束会话”的固定流程。你可以根据你常用AI工具的特性微调。例如如果你用的工具不支持自动读取HUMAN.md你可以把第一步改成“请手动打开并总结根目录的HUMAN.md文件给我看”。定义输出风格在文件中明确你希望AI如何呈现答案。例如“请将关键结论用粗体标出”、“所有命令行指令请放在独立的代码块中”。设置决策过滤器添加一些全局原则例如“在所有方案讨论中优先考虑维护成本低的方案而非技术最前沿的方案”。完成这些后你的知识库就从通用模板变成了一个专属于你的、待命的数字工作伙伴。4. 日常使用流程与高阶协作模式4.1 标准会话工作流一套固定的“仪式”能极大提升人机协作的效率和心智舒适度。以下是我打磨后的日常流程每日启动耗时2分钟在终端或IDE中导航到你的知识库目录cd /path/to/your/ai-vault。启动你的AI助手如在Cursor中打开该文件夹或运行claude .。对AI说“请阅读根目录的HUMAN.md并向我简报当前最紧急的3项任务和今日各项目的下一步行动。”AI会扫描HUMAN.md汇总信息并给出一个清晰的文本摘要。这替代了以往需要自己翻看多个笔记应用的过程。进入具体项目工作你决定今天先处理“Client-X的API开发项目”。告诉AI“我们现在切换到‘02-projects/Client-X-API-Development’项目。请先读取该项目的AGENTS.md文件然后我们开始处理HUMAN.md中列出的‘集成支付网关’这个下一步行动。”AI会读取项目专用的AGENTS.md瞬间获知该项目的所有技术细节、上下文和当前目标然后基于HUMAN.md中的笔记直接开始针对性地工作。你不再需要重复解释“这个API是用FastAPI写的数据库是PostgreSQL支付要用Stripe……”会话结束与知识更新工作告一段落时指示AI“本次会话结束。请更新当前项目的HUMAN.md文件记录我们刚刚完成的支付网关集成步骤、遇到的坑SSL证书问题及解决方案。同时如果项目状态有变如从‘开发中’变为‘测试中’请同步更新根目录HUMAN.md中该项目的状态。”AI会生成更新内容经你确认后写入对应文件。这确保了知识的持续沉淀。如果使用Git最后让AI或你自己执行一个提交git add . git commit -m feat: 完成支付网关集成更新测试记录。4.2 利用模板快速创建新项目当开启一个新项目或新领域时手动创建文件夹和文件很繁琐。利用模板和AI可以一键完成。操作步骤你只需要对AI说“请基于模板在‘02-projects/’下创建一个名为‘[新项目名称]’的新项目文件夹。从‘04-resources/Templates/’中复制AGENTS和HUMAN模板并根据我们刚才讨论的内容初始化它们。”AI会创建文件夹并生成两个初步填写的Markdown文件。你通常只需要在生成的HUMAN.md中补充一些会议要点或初始想法一个结构清晰的项目工作区就准备好了。项目AGENTS.md文件的核心要素一个有效的项目级AGENTS.md应包含项目概述用一两句话说明这是什么项目为谁做核心价值是什么。当前阶段与目标明确当前是探索、开发、测试还是部署阶段本阶段要交付的具体成果。技术栈与环境列出使用的语言、框架、数据库、API密钥位置.env文件、如何启动本地环境。关键约束与决策已知的技术选型原因、需要避开的坑、客户或团队的特定要求。参考与资源链接到相关的设计稿、产品文档、或04-resources/下的参考资料。4.3 与不同AI工具的无缝集成这套方法的强大之处在于其工具无关性。以下是针对不同主流工具的集成要点Cursor原生支持。只需将知识库文件夹作为Workspace打开。Cursor会自动识别项目结构并在会话中利用文件上下文。你可以通过引用特定文件如AGENTS.md来快速注入上下文。Claude Code (Claude Desktop)启动时指定项目目录claude /path/to/your/vault。它会自动读取AGENTS.md和CLAUDE.md模板中已包含指向AGENTS.md。在会话中你可以用/read命令让它读取任何更新后的文件。Windsurf同样以文件夹形式打开项目。Windsurf对项目上下文的管理非常主动经常自动引用相关文件。确保你的AGENTS.md写得足够清晰它能很好地遵循。Aider在启动aider时指定项目根目录它会将该目录下所有相关文件纳入上下文。AGENTS.md文件能帮助它更好地理解项目的整体边界和规则。通用技巧对于任何其他支持读取项目文件的AI工具你只需要确保两件事1. 工具被设置为在该知识库文件夹内工作2. 在会话初期手动发送一条提示“请先阅读本项目根目录下的AGENTS.md文件以了解项目背景。”5. 实战经验、避坑指南与效能提升技巧经过数月的密集使用我积累了大量在模板中不会写的实战心得。这些技巧能帮你绕过弯路直接发挥这个系统的最大威力。5.1 文件维护的“黄金法则”AGENTS.md 要“瘦”HUMAN.md 要“活”AGENTS.md必须保持精简、准确、面向未来。只写AI开始工作时必须知道的核心信息。如果文件超过一屏说明里面混入了过程性笔记或历史记录应该把它们移到HUMAN.md或专门的笔记文件中然后在AGENTS.md里留下链接。一个臃肿的AGENTS.md会降低AI理解重点的效率。HUMAN.md是你的草稿纸。可以用碎片化的句子、待办清单、会议速记、甚至emoji。AI完全能理解这种非正式语言。关键是养成“随时记一笔”的习惯这样会话结束时AI才能帮你系统化整理。根目录HUMAN.md是仪表盘不是数据库 这个文件的目的让你快速“一览众山小”。不要试图在这里记录详细任务或复杂关系。它应该是由各个项目/领域的HUMAN.md自动或半自动汇总而成的“视图”。如果你发现自己在手动维护复杂的列表就该停下来考虑是否需要一个外部的专业任务管理工具如Todoist、ClickUp然后只在根HUMAN.md里放一个链接。“一个项目一个终点”原则 如果一个02-projects/下的文件夹包含了多个不相关的交付物例如既有一个网站重构又有一个数据分析报告请立即拆分。混合上下文会严重干扰AI的判断。清晰的边界是高效协作的前提。5.2 常见问题与排查技巧问题1AI似乎忽略了AGENTS.md文件中的某些指令。排查首先检查AI工具是否真的成功读取了文件。你可以直接问它“请复述一下本项目AGENTS.md中关于技术栈的要求。” 如果它答不上来说明上下文未加载。解决对于Cursor/Claude Code尝试重启会话或在对话中明确引用该文件如“请再次阅读 ./AGENTS.md”。检查文件位置确保AGENTS.md位于你当前工作目录的根层级或直接父级。AI工具通常只自动读取工作区根目录的特定文件。简化指令有时指令过于复杂或模糊。尝试将一条长指令拆分成多条更短、更具体的指令并加上编号。问题2在多人协作或使用多个AI助手时HUMAN.md文件出现冲突或覆盖。预防这是文件系统方案的一个固有挑战。建立团队规则同一时间只有一个“写作者”。或者将HUMAN.md视为一个“只追加”的日志文件所有更新都以带有时间戳的新条目形式添加在顶部而不是修改旧内容。这可以通过在AGENTS.md中给AI设定明确的更新格式来实现。工具辅助如果使用Git冲突可以通过合并来解决。鼓励团队成员在更新前先git pull更新后立即commit push。问题3知识库变得庞大后启动会话变慢或者AI的上下文窗口不够用。优化模块化这是PARA结构的设计优势。确保AI在具体项目内工作时只加载该项目文件夹和必要的04-resources/内容不要让它一次性加载整个知识库。摘要化在根目录或领域级的AGENTS.md中不要粘贴大段代码或文档而是提供摘要和链接。例如“关于系统架构的详细说明请参阅04-resources/System-Architecture.md”。在需要时再指示AI去读取特定文件。定期归档严格执行“完成即归档”。将02-projects/和03-areas/中的已完成或休眠内容移至05-archive/。活跃内容越少认知负荷越低。5.3 高阶扩展与自动化思路当基础工作流稳定后你可以尝试以下扩展进一步提升效率技能Skills/ 斜杠命令Slash Commands集成 许多AI助手支持自定义命令。你可以将常用操作封装成命令。例如在Cursor中创建一个名为/triage-inbox的技能其指令是“读取01-inbox/下的所有文件逐一展示给我并协助我将它们分类到 Projects, Areas, Resources 或 Archive 中。” 这能将一个繁琐的整理过程变成一键操作。自动化脚本 在知识库根目录创建一个scripts/文件夹。可以编写简单的Shell或Python脚本来自动化日常任务。生成周报写一个脚本扫描所有02-projects/*/HUMAN.md文件提取上周的更新条目自动汇总成一份周报草稿。链接检查检查所有Markdown文件中的内部链接是否有效。仪表盘刷新基于各项目的HUMAN.md状态自动更新根目录HUMAN.md中的“即将到期”列表。个性化资源层深化04-resources/不仅可以放About-Me。你可以创建Workflows/存放不同工作类型代码审查、写作、调试的标准操作流程说明。Snippets/存放你常用的代码片段模板并在AGENTS.md中告知AI这个位置。Client-Context/存放不同客户的背景信息、沟通记录、偏好等注意隐私安全。这个由Scott Heffield发起的“Results Studio”模板其精髓不在于那套固定的文件夹而在于它揭示了一种与AI协同工作的范式通过精心设计的、机器可读的上下文文件将人类的意图与AI的执行力无缝衔接。它从你的工作流中抽离了重复的沟通成本让你能更专注于思考和决策本身。我个人的体会是这套系统最大的回报不是立竿见影的速度提升而是一种“心智平静”——你知道你的工作上下文被可靠地记录和结构化随时可供调取这让你敢于在多个项目间快速切换而无需背负记忆的负担。开始可能会觉得维护这些文件是额外工作但一旦形成习惯它就会变成像呼吸一样自然的数字工作仪式。