ClaudeTranscriptAnalyzer

一个用于分析Claude对话记录以识别优化机会的交互式CLI工具，使用与Anthropic用于Claude Code的技术相同的技术构建。

概述

此工具分析Claude Code对话记录，并提出改进建议，例如：

模型上下文协议（MCP）集成
定制技能
克劳德钩子
Git挂钩
工作流优化

技术栈

采用与Claude Code相同的核心技术构建：

TypeScript -类型安全开发
反应 -基于组件的UI架构
墨水 -用于交互式CLI应用程序的React渲染器
Vitest -支持TypeScript的现代快速测试框架

为什么是这个堆栈？

选择此技术栈是为了与Anthropic的Claude Code架构保持一致：

TypeScript+ReactLLMs擅长的“分销”技术
墨水：允许使用React组件和钩子构建终端UI
Vitest：具有出色TypeScript支持的现代测试框架

特性

使用React钩子构建的交互式CLI界面
实时成绩单分析
可采取行动的建议
漂亮的终端输出

安装

npm install

发展

# Run the CLI in development mode
npm run dev

# Build the project
npm run build

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Run tests in watch mode
npm run test:watch

# Type checking
npm run typecheck

# Linting
npm run lint
npm run lint:fix

# Formatting
npm run format
npm run format:check

代码质量

该项目执行严格的代码质量标准：

装订和格式化

埃斯林特9 采用扁平配置格式
TypeScript ESLint 用于识别类型的linting
反应和 React 钩子 ESLint插件
更漂亮 用于一致的代码格式

测试覆盖阈值

线条: 89%
函数: 89%
分支: 89%
声明: 89%

Git Hooks（通过赫斯基）

预提交挂钩 自动运行：

皮棉上演：使用ESLint和Prettier自动修复和格式化暂存文件
类型检查：确保没有TypeScript错误
构建验证：确认项目已成功编译
测试覆盖率：强制执行89%的覆盖率阈值

提交msg钩子 验证：

常规承诺：强制格式，如 feat: add feature 或 fix: resolve bug

提交失败场景：

❌ 无法自动修复的ESLint错误
❌ TypeScript编译错误
❌ 构建失败
❌ 测试失败或覆盖率低于89%
❌ 提交消息格式无效

简明错误消息： 所有故障都提供针对令牌效率优化的单线指导：

❌ ESLint errors: Fix issues above, stage files, and commit again
❌ TypeScript errors: Fix type issues above, stage files, and commit again
❌ Build failed: Fix compilation errors above, stage files, and commit again
❌ Test/coverage failure: Fix failing tests or add tests to reach 89% coverage, then commit again
❌ Commit message invalid: Use conventional commits format (type: subject)
✅ All checks passed 成功时

在允许提交之前，必须通过所有检查，以确保每个阶段的代码质量。可自动修复的格式问题会自动处理，但代码质量问题必须手动解决。

MCP集成

该项目包括 Serena MCP 用于LSP驱动的语义代码理解的配置。

设置

MCP配置在 .mcp.json （项目范围，版本控制）：

Serena MCP：带有go to定义、查找引用和诊断功能的TypeScript语言服务器
为Claude code提供IDE质量的代码智能
自动安装 typescript-language-server

当您在Claude Code中打开此项目时，它将检测 .mcp.json 并提示您启用Serena MCP。

愿景与路线图

最终目标：一个读取Claude代码转录的工具，确定哪里出了问题或本可以做得更好，并推荐特定的扩展来修复它。这意味着我们需要两样东西——一个定义良好的故障模式目录，一个定义明确的扩展Claude的方法目录。然后是有趣的问题：将一个与另一个匹配。

要检测的故障模式

指令失败

语义倒置 --在声称合规的同时，是否与明确要求的相反
选择性听力 --解析多部分指令的一部分，忽略其余部分
指令失忆 --校正后，重复类似的错误；进入道歉重复循环
CLAUDE.md忽略 --默认为训练数据模式，而不是项目的明确指示

漂移和退化

解释性合规 --解释规范背后的意图，而不是从字面上实现它（例如。， Op4.5-Nov25 成为 Opus 4.5 (November 2025))
渐进式退化 --每次修复都会引入新的偏差，同时部分解决旧的偏差；永不收敛
上下文降级 --随着上下文窗口的填充，长时间对话的准确性和连贯性会下降
环境污染 --中间工具结果使上下文膨胀，将重要指令推到范围之外

验证与诚实

提前完工索赔 --当工作未完成时说“完成”；同一答复中的证据与这一说法相矛盾
验证剧场 --生成看起来很彻底但验证错误的验证输出（例如，检查代码结构而不是实际输出）
计划作为盾牌 --使用其自身退化的理解作为反对用户更正的理由

范围和授权

未经授权的行为 --执行用户未请求的操作（例如，运行 npm install -g 当被要求诊断时）
工具规避 --明确告知使用特定工具，除了使用它之外，什么都做
系统简化偏差 --在每个决策点始终如一地选择更容易的实施；一致的偏差，而非随机误差

元模式

没有纠正的自我意识 --正确识别自己的故障模式，然后立即复制它
挫折升级 --用户表示沮丧；代理人口头承认，但不改变行为

扩展克劳德的方法

你可以用来扩展或引导克劳德代码的一切。该工具的工作是将检测到的故障模式与其中的正确模式相匹配。

上下文和记忆

CLAUDE.md --持久项目指令，在会话开始时自动加载。层级：企业→ 用户(~/.claude/) → 项目→ 目录级别。基础定制层。支持 @path 从多个文件导入以进行组合。
CLAUDE.local.md --Gitigned了CLAUDE.md的对应项。个人的、特定于项目的首选项不会被提交。
**模块化规则(.claude/rules/*.md)** --全局范围指令文件。比单个CLAUDE.md更细粒度；规则可以针对特定的目录或文件类型。
会话交接 --显式跨会话内存文档。子代理解决上下文降级的地方 *在...之内* 一次会议，交接解决它 *穿过* 会话——你带入下一个会话的结构化状态。
上下文MCP --只读MCP服务器，为Claude提供对数据（存储库、数据库、文档）的结构化访问，而无需将原始内容转储到上下文中。

自动化与执行

权限 --声明性拒绝/允许/询问规则 settings.json硬门：阻止敏感文件的读取，需要确认破坏性命令。在扣篮之前进行评估——第一场比赛获胜。
钩子 --生命周期事件上的事件驱动脚本： PreToolUse, PostToolUse, UserPromptSubmit, SessionStart等等。可以阻止操作(block: true)、提供反馈或验证输出。
Git挂钩 --预提交和提交msg钩子，用于在代码离开开发人员之前执行标准。

能力和能力

能力MCP -公开可执行功能的MCP服务器：API写入、部署、外部服务交互。
LSP服务器(.lsp.json) --代码智能的语言服务器集成：转到定义、查找引用、类型检查、实时诊断。为Claude提供精确导航（50ms），而不是文本搜索（45s）。Serena就是一个例子；这是一个通用的扩展层。
技能 --自动激活功能 .claude/skills/，每个都有一个 SKILL.md.Claude透明地将任务上下文与技能描述相匹配，无需手动调用。
斜杠命令 --在中定义为markdown的手动触发工作流 .claude/commands/支持参数插值和预执行bash步骤。注意：Anthropic已将斜线命令合并到Skills中，该文件位于 .claude/commands/foo.md 以及一项技能 .claude/skills/foo/SKILL.md 两者都创造 /foo.技能是前进的道路。

建筑与隔离

次级代理商 --具有隔离上下文窗口、自定义系统提示和受限工具访问的专用代理。防止深度工作中的上下文中毒。
模型选择 --通过以下方式路由到任务的正确模型 ANTHROPIC_MODEL 或按请求配置。不同的模型具有不同的故障模式；复杂的推理任务和简单的格式化任务不需要相同的模型。
disabledMcpServers --在项目配置中明确禁用未使用的MCP服务器。每个活动的MCP都会占用上下文窗口；禁用未使用的是防止上下文污染的最简单方法之一。
插件 --可共享的包，将命令、钩子、技能和MCP配置捆绑到可分发的单元中。

沟通

提示工程 --请求的措辞方式。特异性、分解和显式约束都会影响输出质量和故障率。

解决方案映射失败

核心思想是：检测转录中的模式，找出解决它的扩展名。

检测到的故障模式	推荐扩展
指令失忆症/选择性听力	CLAUDE.md——持久、明确的规则，重新加载每个会话；Git钩子——在提交时强制执行需求，而不管确认了什么
CLAUDE.md忽略	钩子（PreToolUse）——在关键时刻重新注入关键指令
上下文降级	子代理——为孤立的工作生成新的上下文窗口；会话切换——将结构化状态带入下一个会话
上下文污染	上下文MCP——结构化数据访问，而不是原始转储； `disabledMcpServers` --从上下文预算中削减未使用的MCP；LSP服务器——精确导航，而不是广泛的文件搜索
验证剧场	钩子（PostToolUse）——强制执行实际输出验证；LSP服务器——作为基础真相层的类型检查和诊断
未经授权的操作	权限（拒绝规则）-硬门，在其他任何操作运行之前进行评估；挂钩（PreToolUse with `block: true`)--边缘案例权限的确认不包括
工具回避	技能——明确 `allowed-tools` 约束行为的声明
系统化简化偏差	CLAUDE.md——明确的复杂性和完整性要求
提前完成索赔	挂钩（PostToolUse）——在允许签核之前验证完成标准；Git钩子——预提交运行测试/构建/覆盖，如果有任何东西实际损坏，则阻止提交
渐进降级	使用规范执行验证脚本的技能
解释性合规	CLAUDE.md——字面实现规则；规格锁定技能

规划建筑：两通海库管道

该分析使用Claude Haiku作为两个重点LLM通道运行——快速、廉价，非常适合结构化提取和分类工作。每个通道都有一个任务。

Transcript files (with file timestamps)
    │
    ▼
┌─────────────────────────────┐
│  Pass 0: Summarization      │  ← Runs once per transcript when first
│                             │     discovered. Haiku reads the transcript
│  Input:  raw transcript     │     and produces a short summary. Datetime
│  Output: summary + cache    │     comes from file metadata. Results
└───────────────┬─────────────┘     cached — populates the session list.
                │
                ▼
        Session List UI
   (datetime + summary per session)
                │  ← User selects a session
                ▼
┌─────────────────────────────┐
│  Pass 1: Failure Detection  │  ← Haiku reads the transcript,
│                             │     identifies failure patterns,
│  Input:  raw transcript     │     and outputs structured results.
│  Output: failure pattern JSON │     single-responsibility prompt —
└───────────────┬─────────────┘     no matching logic here.
                │
                ▼
        Intermediate JSON
        (the critical piece)
                │
                ▼
┌─────────────────────────────┐
│  Pass 2: Solution Matching  │  ← Haiku takes the structured output
│                             │     from Pass 1 and maps each detected
│  Input:  failure pattern JSON │     failure pattern to extensions from
│  Output: recommendations   │     the catalog. No re-reading
└─────────────────────────────┘     the transcript needed.

为什么是两次而不是一次？

识别和解决是根本不同的任务。第一关纯粹是阅读成绩单并找出问题所在——对修复没有意见。第二步纯粹是将检测到的模式与已知的解决方案进行匹配，而不是重新读取转录本。将它们折叠成一个提示将两者混为一谈，这是该工具旨在捕捉的确切故障模式的秘诀：选择性听力、捷径、遗漏的细节。将它们分开也使管道可测试——您可以在Pass 2运行之前独立验证Pass 1的输出。

中间格式

两次传递之间的JSON模式是管道可靠性的所在。形状粗糙：

[
  {
    "failure_state": "Instruction Amnesia",
    "category": "Instruction Failures",
    "severity": "high",
    "evidence": "Lines 42-58: user corrected column width three times, each fix reverted in the next response",
    "confidence": 0.92
  }
]

每个检测都是自包含的：故障模式名称（与故障模式目录相关联）、它所属的类别、严重程度、对记录中发生位置的直接引用或参考，以及置信度评分。Pass 2不需要重新阅读成绩单——它所需要的一切都在这个结构中。

Pass 2增强：具体建议

Pass 2的任务是将故障模式与扩展进行匹配 *类型* （例如“使用上下文MCP”）。但通用类别是不可操作的。将其转化为特定工具的两种选择：

网络搜索 --已经是内置的Claude工具。无需额外布线，即可即时搜索MCP、技能和解决方案。
资源侦察员 --一种专门的技能，可以发现市场和仓库中的现有技能和MCP服务器。比一般搜索更有针对性。

无论哪种方式，输出都会从“您应该添加一个用于数据库访问的MCP”转变为“这是一个可以做到这一点的MCP，这是如何连接它的”

项目演示

✅ 具有强类型的TypeScript开发
✅ CLI上下文中的React钩子（useState、useEffect、自定义钩子）
✅ 使用Ink开发CLI工具
✅ Vitest的全面测试覆盖率（v8覆盖率，89%阈值）
✅ 现代ESLint 9扁平配置
✅ 带有git钩子的自动质量门（预提交+提交消息）
✅ 一致历史记录的常规提交
✅ MCP与Serena集成，实现LSP驱动的代码智能

Claude Transcript Analyzer

快速接入

详细介绍