AI编程助手思考日志插件：结构化记录Claude Code的推理过程

1. 项目概述一个为AI编程助手打造的内省日志插件如果你和我一样日常重度依赖像Claude Code这样的AI编程助手来辅助开发那你肯定遇到过这样的场景面对一个复杂的重构任务你向AI助手提出需求它开始一步步地生成代码、解释思路。整个过程可能持续十几轮对话涉及多个决策点。几天后当你想回顾“当时为什么选择方案A而不是方案B”或者“那个棘手的边界条件是怎么解决的”时却发现记忆已经模糊只能在一长串聊天记录里大海捞针。这正是我开发Thinking Log Plugin的初衷——为AI辅助编程过程建立一个系统化的“思考飞行记录仪”。这个插件本质上是一个Claude Code的扩展工具它的核心使命是自动化地记录并结构化Claude在协助编码时的整个推理链条。它不仅仅是保存聊天记录而是将散落在对话中的“思维碎片”——包括问题分析、方案权衡、决策依据、执行动作和最终结果——提取出来按照统一的模板整理成一份可读、可查、可复现的文档也就是项目根目录下的THINKING_LOG.md文件。想象一下这就像给你的AI搭档配了一个专属的“工程笔记”每一次重要的技术讨论和决策都会被自动归档。我之所以认为这个工具不可或缺是因为在现代开发流程中AI已经从一个简单的代码补全工具演变成了一个能够参与系统设计、算法选择和问题排查的“初级工程师”。这个过程产生的“中间产物”——即它的思考过程——其价值往往不亚于最终生成的代码。这些思考过程是理解代码意图、复盘错误决策、进行知识传承的关键资产。然而这些信息天然是非结构化和易失的。本插件通过强制性的结构化记录将这些资产固化下来特别适合独立开发者、技术负责人或是在进行复杂项目攻坚、代码审查和新人onboarding的团队使用。2. 核心设计思路与架构解析2.1 解决的核心痛点从信息洪流到知识图谱在深入代码之前我们先厘清这个插件要解决的根本问题。当Claude Code处理一个任务时其输出是线性的、对话式的文本流。其中混杂着对需求的理解与分析“用户想要一个缓存模块需要处理并发和过期”。可能的解决方案与权衡“可以用内存缓存也可以用Redis前者简单但重启失效后者需要外部依赖”。最终决策与理由“鉴于本项目是轻量级工具选择内存缓存使用lru-cache库”。具体的实施步骤与代码“首先安装依赖然后创建CacheService类实现get、set、delete方法”。遇到的问题与调试过程“发现内存泄漏原因是闭包引用通过WeakMap解决”。传统上这些信息要么丢失要么需要开发者手动从聊天记录中摘抄整理效率极低且容易遗漏关键决策上下文。本插件的设计思路就是通过预定义的触发规则和日志模板在恰当的时机自动捕捉这些信息并将其映射到一个结构化的文档模型中。这个模型我称之为“FTDAR”模型Flow-Thinking-Decision-Action-Result它构成了每一则日志条目的骨架确保记录既完整又聚焦。2.2 插件架构技能Skill与命令Command的双引擎驱动Claude Code的插件体系主要包含两种扩展方式技能Skill和命令Command。本插件巧妙地结合了二者以实现自动触发与手动调用的无缝衔接。技能Skill是核心。它本质上是一组预定义的提示词Prompt和上下文规则。在skills/thinking-log/SKILL.md文件中我定义了这个技能何时被激活。它不是一直运行而是设置了智能触发器。例如当检测到用户消息中包含“解释一下你的思路”、“记录决策过程”或“thinking log”等关键词时或者当Claude判断当前任务步骤繁多、复杂度高时该技能会自动激活。一旦激活Claude就会在生成常规代码回复的同时按照FTDAR模型组织其“内心独白”并准备将其追加到日志文件中。这种基于语义的自动触发机制是保证日志持续性的关键避免了每次都需要用户手动提醒的麻烦。命令Command则提供了精确的控制。在commands/thinking-log.md中我定义了/thinking-log这一系列子命令为用户提供了管理日志的“控制面板”。比如当你开始一个新项目模块时可以手动执行/thinking-log init来初始化一个新的日志文件在完成一个重大特性后可以用/thinking-log summary来生成阶段性的总结。命令系统弥补了自动触发可能存在的遗漏给了用户最高的管理权限。这种“自动记录为主手动管理为辅”的架构既保证了思维的连贯性被忠实记录又赋予了开发者足够的灵活性和控制力是经过实践验证的可靠设计。2.3 存储策略设计项目隔离与隐私考量日志文件放哪里这是一个看似简单却至关重要的设计决策。将THINKING_LOG.md直接放在项目源码根目录下是最简单的但这会带来几个问题首先它可能包含你对项目架构的犹豫、对某些依赖的负面评价等“不成熟的想法”这些信息不一定适合提交到版本库供所有协作者查看。其次它属于AI生成的辅助性文档而非项目功能源码混在一起会污染项目结构。因此插件采用了双存储位置策略默认位置推荐~/.claude/projects/{project-name}/docs/THINKING_LOG.md项目本地位置需--project标志{project-root}/docs/THINKING_LOG.md默认位置位于Claude Code的本地配置目录中与你的聊天历史、项目配置在一起。这样做实现了关注点分离项目仓库里是干净的、可交付的代码而AI辅助生成的、包含大量探索性思维的日志则保存在你的本地工作区。这对于团队协作、开源项目贡献或者公司有严格代码审查政策的环境尤为重要。当你确实需要将日志作为项目文档的一部分时例如用于记录重大的架构决策过程再通过/thinking-log add --project命令将其保存到项目本地。3. 核心功能与使用模式深度解析3.1 结构化日志模板FTDAR模型实战插件的核心价值体现在它生成的每一则日志条目上。我设计的FTDAR模板不是随意拼凑的每个部分都有其明确的意图和填写规范。以一个真实的例子来说明。假设我们正在实现一个用户上传图片的API端点Claude的思考过程被记录如下### 2024-05-27 14:30:15 - 设计图片上传API端点 **Flow:** mermaid flowchart TD A[客户端请求上传] -- B{验证文件类型与大小} B --|无效| C[返回400错误] B --|有效| D[生成唯一文件名] D -- E[保存文件至临时目录] E -- F[异步触发缩略图生成] F -- G[将文件信息存入数据库] G -- H[返回201 Created及文件URL]Thinking:用户需要上传个人头像。主要风险在于1. 文件类型限制仅允许JPG/PNG。2. 文件大小限制防止DoS攻击。3. 文件名冲突和安全避免路径遍历。4. 性能问题大文件阻塞请求。是否需要同步处理缩略图这可能导致响应时间过长。更好的做法是主流程只保存原文件通过消息队列异步处理缩略图但这样系统复杂度会增加。考虑到当前是MVP版本同步处理虽然慢但实现简单可以后续优化。Decision:采用同步处理方案但在代码中预留异步接口generateThumbnailAsync并为文件大小设置一个较低的上限2MB以控制单次处理时间。使用uuid库生成唯一文件名结合path.join安全拼接路径。Action:在Express路由中添加/api/upload/avatarPOST端点。使用multer中间件处理multipart/form-data。在multer配置中设置文件过滤器和大小限制。在控制器中调用fs.rename移动文件然后同步调用sharp库生成缩略图。将原文件路径、缩略图路径、用户ID写入User模型。Result:端点功能完成。使用Postman测试上传1.5MB的PNG文件成功返回了正确的URL。响应时间约800ms其中缩略图生成占用了约600ms。确认了性能瓶颈在日志中标记了“待优化缩略图生成应异步化”。**各部分解读** - **Flow (流程图)**用Mermaid语法快速可视化了整个API的处理流程。这对于理解数据流向和关键判断分支至关重要尤其是在向他人解释或自己回顾时一图胜千言。 - **Thinking (思考过程)**这是最宝贵的部分记录了“为什么”。它包含了被否决的选项异步队列及其优缺点以及选择当前方案同步处理的**权衡理由**MVP版本、实现简单。这避免了日后看到代码时产生“当时为什么不用更优的方案”的疑问。 - **Decision (决策)**将思考的结论明确固化下来。这里明确了技术选型uuid, path.join, multer、关键参数2MB限制和架构预留异步接口。 - **Action (行动)**具体的、可执行的步骤列表。这相当于一个微型的工作清单清晰地说明了“做了什么”。 - **Result (结果)**记录执行后的状态、测试结果和**新发现的问题**性能瓶颈。这为下一次迭代优化提供了直接的输入。 **实操心得**在编写“Thinking”部分时我鼓励Claude也建议用户不仅写下最终选择的理由更要写下被放弃的选项。这能极大地提升决策过程的可追溯性。例如记录下“考虑到项目初期快速验证的需求暂时牺牲性能以换取更简单的部署和调试”这样的上下文在项目后期进行技术债评估时价值连城。 ### 3.2 可视化利器Mermaid图表的集成与应用 文字描述流程总有局限一张清晰的图表能瞬间提升理解效率。插件深度集成了Mermaid图表支持多种类型适应不同场景 1. **流程图 (flowchart)**: 最适合描述业务逻辑或算法步骤如上例中的API流程。 2. **序列图 (sequenceDiagram)**: 当需要理清多个服务、模块或类之间的交互时序时它无可替代。例如记录一个微服务调用链前端 - 网关 - 认证服务 - 业务服务 - 数据库。 mermaid sequenceDiagram participant C as Client participant G as API Gateway participant A as Auth Service participant S as User Service participant D as Database C-G: POST /api/users (with Token) G-A: Validate Token A--G: Token Valid (UserID) G-S: CreateUser(UserData, UserID) S-D: INSERT INTO users ... D--S: OK S--G: 201 Created G--C: 201 Created 3. **思维导图 (mindmap)**: 在项目初期进行技术选型或架构脑暴时非常有用。可以快速勾勒出技术栈的各个组成部分及其备选方案。 4. **Git图谱 (gitGraph)**: 记录复杂的分支合并策略。例如在实现一个需要从feat/auth分支合并到develop再创建hotfix/login-bug分支的流程时用图表记录一目了然。 **注意事项**Mermaid图表虽然强大但不宜过度使用或过于复杂。我的经验是一个日志条目中图表应聚焦于说明**一个核心流程或关系**。如果逻辑非常复杂可以拆分成多个条目或者用文字辅助说明。插件自带的references/advanced-patterns.md提供了一些复杂图表的绘制技巧例如如何优雅地处理循环和条件分支。 ### 3.3 智能触发与手动命令的协同 理解了架构我们来看看具体如何与插件交互。其操作模式分为被动触发和主动命令。 **自动触发技能**这是插件的“自动驾驶”模式。你不需要做任何特殊操作只需像往常一样与Claude Code对话。当对话触及以下情况时技能会被自动激活Claude会在后台准备日志条目 - 你明确要求“请记录下你实现这个函数的思路。” - 任务本身很复杂Claude检测到多步推理例如重构一个包含多个类的模块。 - 你提到了关键词如“我们做个决定”、“记录一下这里为什么这么选”。 - 在代码生成过程中涉及到了明显的方案选择例如选择使用fetch还是axios。 激活后Claude通常会在回复完主要代码后附加一句提示如“*上述实现思路已记录至思考日志*”。日志内容已经自动写入到THINKING_LOG.md文件。 **手动命令控制台**当你需要更精细的控制时就需要使用/thinking-log命令。以下是最常用的几个子命令及其使用场景 - /thinking-log init在一个新项目或新模块开始时使用。它会创建一个带有项目名称和初始说明的崭新日志文件。**建议在每个新的代码仓库或功能目录下首先运行此命令**。 - /thinking-log add --title \优化数据库查询\当你完成了一个重要但可能未被自动捕捉的任务时例如你手动优化了一个SQL查询可以用此命令手动添加一条记录。--title参数给条目一个清晰的标题。 - /thinking-log summary在完成一个功能模块、一个冲刺Sprint或者解决一个复杂Bug后运行。它会提示Claude对过去一段时间或整个日志的思考过程进行**归纳和总结**生成一段高层次的概述这对于编写周报或项目复盘极具价值。 - /thinking-log show快速在聊天窗口中显示最近几条日志或日志的存储状态方便你即时查看而不必离开编辑器。 ## 4. 高级应用模式与集成实践 ### 4.1 将思考日志融入开发工作流 一个工具只有融入现有流程才能发挥最大价值。以下是我将Thinking Log与日常开发结合的几个实践 **1. 代码审查Code Review的前置材料**在发起Pull Request (PR) 时我不再只提交代码diff。我会将相关功能开发过程中产生的THINKING_LOG.md片段通过/thinking-log show筛选作为PR描述的一部分。审查者不仅能看“代码是什么”还能看到“代码为什么是这样”理解背后的权衡和决策这使得审查更深入、高效减少了来回沟通的成本。 **2. 技术决策记录ADR - Architecture Decision Record的草稿**当项目面临重要的技术选型如选择React vs Vue或选择REST vs GraphQL时与Claude的讨论过程本身就是一个完善的决策分析。思考日志自然形成了ADR的初稿。你只需要将相关的“Thinking”和“Decision”部分稍作整理就能生成一份格式规范的ADR文档。 **3. 新人 onboarding 与知识传承**新成员加入项目时面对庞大的代码库常常无从下手。这时一份按时间顺序记录的思考日志就是最好的“代码游记”。新人可以沿着日志看到每个核心模块是如何从无到有、经历了哪些问题、又是如何解决的能快速理解系统的演进脉络和设计哲学比直接阅读最终代码有效得多。 **4. 个人复盘与技能提升**定期比如每周回顾自己的思考日志。你会发现自己在某些类型问题上反复纠结或者在决策模式上有可以优化的地方。这就像程序员的“错题本”和“思维训练册”是提升解决问题和系统设计能力的绝佳材料。 ### 4.2 自定义与扩展让插件更贴合你的习惯 开源插件的好处在于你可以按需定制。虽然插件提供了良好的默认设置但你可能需要调整以适应团队规范或个人偏好。 **1. 自定义日志模板**如果你觉得FTDAR模型不完全适用可以修改skills/thinking-log/references/starter-template.md文件。例如你的团队可能更强调“背景Context”和“相关方Stakeholders”那么你可以创建一个新的模板 markdown ### {Timestamp} - {Title} **背景:** [问题产生的场景和约束] **思考与分析:** [Claude的推理] **决策:** [最终方案] **依据:** [参考的文档、数据或原则] **实施:** [具体改动] **验证结果:** [测试和上线情况]然后在SKILL.md中修改提示词让Claude按照新模板填充内容。2. 集成外部工具思考日志是纯文本Markdown文件这使其易于与其他工具集成。与笔记软件集成你可以写一个简单的脚本如Python或Shell定期将THINKING_LOG.md同步到Obsidian、Notion或你的Wiki中建立知识链接。生成报告使用pandoc或类似的Markdown处理工具可以将日志转换为PDF或HTML格式的周报、月报。关键信息提取通过脚本解析日志自动提取所有“Decision”条目生成一份项目关键决策清单。3. 调整触发敏感度如果你觉得插件触发过于频繁或不够频繁可以编辑SKILL.md中的激活条件。例如你可以增加更具体的触发短语或者修改Claude判断“复杂任务”的内部逻辑这通常涉及对提示词的微调。5. 常见问题、排查与优化心得在实际使用和推广这个插件的过程中我和其他用户遇到了一些典型问题。这里做一个集中梳理和解答。5.1 安装与基础使用问题Q1: 执行/plugin install命令后插件没有反应或报错。A1: 首先请确保你的Claude Code是最新版本。旧版本可能对插件系统支持不完善。其次检查网络连接因为安装需要从GitHub拉取代码。最可靠的安装方式是手动安装在终端中克隆或下载插件仓库到本地。找到你的Claude Code插件目录。通常在~/.claude/plugins/Linux/macOS或%USERPROFILE%\.claude\plugins\Windows。将整个thinking-log-plugin文件夹复制到该目录下。重启Claude Code桌面应用或编辑器插件。手动安装能避免很多网络和缓存问题。Q2: 技能没有自动触发即使我在进行复杂任务。A2: 自动触发依赖于Claude对对话内容的分析。请尝试在对话中更明确地使用触发词如“请记录你的推理过程”、“把我们的讨论记到思考日志里”。检查技能是否已正确加载。在Claude Code中有时可以查看已加载的技能列表。如果始终不触发可以暂时依赖手动命令/thinking-log add来记录。自动触发是一个优化功能手动命令才是确保记录不丢失的保障。Q3: 日志文件被创建在了错误的位置或者我找不到它。A3: 牢记插件的双存储策略。首先确认你最近一次操作是否使用了--project标志。如果没有日志默认在~/.claude/projects/{project-name}/docs/下。{project-name}通常是当前打开的工作区文件夹名称。你可以随时使用/thinking-log show命令它会显示当前日志文件的完整路径。5.2 内容与格式问题Q4: 生成的Mermaid图表语法错误无法渲染。A4: 这是最常见的问题之一。Claude生成的Mermaid代码偶尔会有拼写错误或格式问题。解决方案是使用在线编辑器验证将出错的代码块复制到 Mermaid Live Editor 中编辑器会高亮显示语法错误方便你定位修正。简化图表在提示中要求Claude生成更简单、更标准的流程图。复杂的逻辑可以分多个简单图表表示。手动修正后作为范例当你手动修正了一个图表后可以将正确的代码片段作为“范例”提供给Claude它会在后续生成中学习你的偏好。你可以把这个范例保存在项目的某个文档中需要时引用。Q5: 日志条目过于冗长或琐碎如何把握记录的粒度A5: 这是一个需要平衡的艺术。我的经验法则是记录“为什么”而非“是什么”对于简单的语法糖、工具函数调用无需记录。重点记录那些有决策点、涉及方案权衡、或解决了非显而易见问题的时刻。以“任务”为单位完成一个相对独立的功能点如“实现用户登录API”、“修复数据导出时的内存溢出BUG”后生成一条总结性的日志。过程中的一些小步骤可以合并。善用“Result”部分进行反思如果某个实现后来被证明有问题可以在原日志的“Result”部分追加后续的发现和修正形成完整的“问题-解决-复盘”闭环。Q6: 团队中多人使用日志会冲突吗A6: 如果使用默认的本地存储在~/.claude/下那么每个人的日志都是独立的不会冲突。这适合个人记录。如果团队希望共享一份“集体思考日志”则需要统一使用--project标志将日志保存在项目仓库内。此时需要像对待代码一样对待这个文件在编辑前先拉取最新版本编辑后及时提交避免合并冲突。更高级的用法是每个人维护自己的日志文件然后定期由负责人汇总精华部分到项目主文档中。5.3 高级技巧与优化建议1. 为日志条目打标签在标题或内容中使用[BugFix]、[Refactor]、[Perf]、[Security]等标签后期可以通过文本搜索快速过滤特定类型的记录。2. 建立日志索引在THINKING_LOG.md文件的顶部维护一个简单的索引表链接到重要的决策或问题解决条目。markdown # 思考日志索引 - [认证系统设计决策](#session-2024-05-10) - 2024-05-10 - [数据库连接池泄漏排查](#session-2024-05-15) - 2024-05-15 - [选择GraphQL而非REST的原因](#session-2024-05-20) - 2024-05-203. 定期清理与归档对于一个长期项目日志文件可能会变得很大。建议每月或每季度将旧的日志条目移动到一个按时间命名的归档文件如THINKING_LOG_2024_Q1.md中并在主日志文件里保留链接。这能保持主文件的轻量和可读性。4. 将日志作为提示词的一部分在进行深度迭代或修复相关Bug时你可以将之前相关的思考日志内容作为上下文提供给Claude。例如“关于用户认证模块我们之前的讨论记录在[这里]当时选择了JWT方案。现在遇到一个Token刷新问题请基于之前的决策继续分析。” 这能让Claude保持上下文的一致性避免重复已经讨论过的内容。经过数月的使用我最大的体会是这个插件改变的不仅仅是一种记录习惯更是一种与AI协作的思维方式。它迫使你和AI将隐性的、跳跃的思维过程显性化、结构化。最终积累下来的不仅是一份项目日志更是一部生动的项目成长史和一部属于你个人的“AI结对编程”最佳实践手册。