AiRemember 工程经验百科

Appearance

Claude 习惯 ​

会话/提示词/工具链习惯 ｜ 数据源：本地 txt（唯一真相源）

02 | Claude Code 使用习惯与避坑（L4 重建版）

一、问题层：发生了什么 ​

  1. 上下文死锁（2026-08-23，会话 22f6e7ef，记忆 claude-session-context-overflow-recovery）： 本机模型 deepseek[1m]=1,048,576 token，会话逼近上限时任何请求（含 /compact）都 400 死锁—— /compact 也必须携带全部历史，messages+32000 超限连压缩都发不出。当日隧道页面会话 1,016,645 token（距上限差 69 token）与 AISC 会话双双卡死。

  2. 并发 git 挤掉 HEAD（2026-08-25，会话 7f011b79，记忆 git-repo-concurrent-session）： 工作区多 CLI 并行，另一会话 git add -A 提交推送，挤掉自己的 HEAD、清掉未提交改动、 中断 cherry-pick；部署 PMS 留言板时提交 e2c93615 后被并发会话基于它继续提交， 误判"提交丢失"。

  3. 坏 hook 阻塞全部工具（2026-08-25，会话 2e4992d6/29ba1861/4bc2bb55）： settings.json 的 hook 指向失效路径（trigger_light.py 迁移后未改）→ 每次工具调用被拒， 连 Read/Edit 都动不了，只能用户 ! 前缀手动修；另一案例 Stop hook 的 & PowerShell 语法 在 bash 执行，每轮回复结束轰炸 syntax error。

  4. GBK 编码误诊（2026-08-21，会话 2bb17633）：审批接口 500 查 1.5 小时——真因是 Windows curl 发中文 JSON 按 GBK 编码（0xc9 字节），服务端 UTF-8 解析失败；换个 ASCII payload 第一分钟就能测出。

  5. claude --resume 项目目录约束（2026-08-24，会话 984446a0，doc 782）：终端续聊 "No conversation found"——resume 只在当前项目目录搜会话，桂平会话 869150ac 属于 C:\Users\AI 项目，而按钮在 Ai-sync-chat-AISC 目录运行 → 找不到。

  6. 版本判定用 hash 永远不相等（2026-08-23，AISC v0.6.2b）：服务器 version.txt 存部署时 git hash vs 客户端 HEAD hash 每次提交都变 → 误报"代码过旧"上百遍（doc 772 记录）。

二、对策层：怎么解决（可执行） ​

  1. 上下文死锁恢复五步（实测流程）： ① 定位卡死会话（~/.claude/projects/<项目>/ 最大 jsonl，grep 片段确认） ② 备份为 <file>.jsonl.<日期>.bak（.bak 后缀避免被 --resume 列表拾取） ③ python 裁剪：保留首行 + 尾部 800 行（≈230k tokens）写回原文件 ④ 用户先关掉卡死的旧窗口（裁剪只对新加载有效） ⑤ claude --resume &lt;sessionId&gt; 显式指定恢复；不用 --continue（会续到最近会话） 预防：后台大输出快速撑爆上下文，接近上限前主动 /compact

  2. 并发 git 纪律： ① 提交+推送一条 && 链一气呵成（减少窗口期） ② 只 git add 自己的文件，禁 add . ③ 内容被挤掉先 git cat-file -t <hash> 确认对象仍在，git show <hash>:<path> 提取 （注意 path 相对仓库根，非 cwd——写错静默输出空） ④ 推送前 fetch 对齐；"有改动但 status 不显示"先 git log --oneline -3 看祖先链

  3. hooks 配置三规则： ① hook 必须指向存在的脚本（迁移项目后同步改 hook） ② hook 命令匹配实际 shell（bash 里禁 &amp; PowerShell 语法；Windows 无 bash 的插件 hook 禁用） ③ hook 配置会话启动时加载——改文件必须重启会话；出问题用 ! 前缀手动修或 rollback

  4. 编码铁律：中文参数/内容一律 UTF-8 文件体 + base64 传输（Git Bash 传中文 argv 是 GBK）； PowerShell 5.1 输出 GBK → 加 PYTHONIOENCODING=utf-8 / chcp 65001 / "shell": "powershell"

  5. resume 修复命令（doc 782 方案）： cd /d C:\Users\AI && claude --resume 869150ac...（先 cd 到会话所属项目目录再 resume）

  6. 多 CLI 协作纪律（doc 840 实操验证）：

    • git add <精确路径>，禁止 git add .
    • 推送前 git fetch 对齐（远端随时被其他会话推进）
    • amend 仅限未推送提交
    • Git Bash 调 Windows 工具：robocopy 用 //E 或 MSYS_NO_PATHCONV=1（/E 被路径转换吃掉）
    • 盘点结论必须带时间戳（skills 目录 2 分钟从 1286 变 75 个的教训）

  7. 交付自检体系（doc 628）：五件套 + A-E 自检（A 功能实测/B 接口含 401/C 浏览器初始加载/ D 安全/E 交付核对）+ 易漏项沉淀 + 三层测试（L1 本地/L2 接口/L3 浏览器 agent-browser）

补充经验点（M2 批次 2a 第二轮 AI 总结，2026-08-27，JSON Schema 10 条 style_check 0 拦截）：

  • Cursor 上下文限制（17f69885）：一次只能改几个文件——复杂任务回 Claude Code（1M）
  • settings 硬阻断实测不生效（310e122b）：改后重启验证；settings/local 层级区分
  • 上下文堆积预防（b8021964）：接近上限主动 /compact；后台输出重定向
  • 日志死锁（feb5ab91）：BeginInvoke 跨线程 → 队列入队+UI 定时刷新
  • 日志独立性判断（54392a07）：统一 _notify 必写日志 + 渲染日志
  • UTF-8 无 BOM 解析错误（c140528c）：脚本编码统一决策
  • GBK 检测（6164c80c）：FixGbk 856 行——PYTHONIOENCODING 根治
  • 模型配置切换（8deba434）：env 块全量替换（重复记录，M1 已有）
  • 三服命令编排（ee784016）/ 验证码连续性（66215eaf）：反爬限流

补充经验点（M2 批次 2a 第三轮 AI 总结，2026-08-27）：

  • 先喂足上下文再开工（38c16180）：任务前完整上下文供给是高效专业的前提
  • stop hook 异常（2e4992d6）：hook 指向存在脚本 + 重启验证（与 I-025 互证）
  • settings 修复排查（273f9c29）：逐键校验结构
  • 提醒中心跳回（cb2e9257）：_focus_key 强制定位/去抖
  • 特批通道写经验（163ed12d）：网关特批 + 脚本文件方案
  • 观测：第三轮命中率 ≈55%（尾部衰减同 M1 模式）——2a 候选 89 会话尾部弱相关

三、证据层：来源 ​

  • 记忆 claude-session-context-overflow-recovery：死锁机制 + 恢复流程

  • 记忆 git-repo-concurrent-session：并发挤 HEAD + git show 路径坑

  • 会话 4bc2bb55：& 语法轰炸全程 + "重启才能消除"结论

  • 会话 2e4992d6：坏 hook 阻塞全部工具 + 手动修复指引

  • 记忆 win-bash-curl-gbk-encoding：GBK 中文参数坑

  • doc 628：交付自检 A-E（配套体系）

  • 框架体系关联（非内容支撑，不计入引用计数）：方法论文档 938/932——本主题为框架四层标准实施内容之一

【四、优化层：下一步行动项

  1. 收尾仪式加"hook 路径存在性校验"（I-025 落地：脚本检查 settings.json 所有 hook 目标文件存在）
  2. 上下文预警：接近 1M 上限时自动提示（AAC token_check 联动）
  3. 编码坑沉淀为脚本：一条 utf8 环境初始化片段（PYTHONIOENCODING + chcp + -X utf8）入项目模板 （产出：.byaysun-ai-v1/scripts/env_utf8.sh；触发：新项目脚手架生成时）
  4. 五问自检中加 Q：本任务涉及多 CLI 并发？hook 目标存在？——防复发 （产出：delivery_audit.py 增加 hook 目标存在性检查项；触发：每次交付审计）
  5. 上下文预警自动化（产出：AAC token_check 加"逼近 1M 上限"告警；触发：会话 token 达 80% 上限时）——死锁预防从"事后恢复"变"事前预警"
  6. 会话恢复流程脚本化（产出：scripts/resume_session.py，参数=会话 id，自动定位项目目录 并输出 resume 命令；触发：resume 报 No conversation found 时）
  7. 多 CLI 并发告警（产出：提交前 git fetch 自动检查 ahead/behind 并提示；触发： 每次 commit 前，配合 doc 840 纪律）——并发挤 HEAD 从"事后恢复"变"事前规避"

一、问题层（增补） ​

  • 模型名不识别触发 auto-compact 误压缩（3 会话：06d46abc/322a42f4/461b341e）
  • hooks 三大坑：& bash 冲突/插件 bash 报错/编码打架
  • hooks 配置会话启动缓存（改了不生效）
  • git 提交挂点：secret_scan 性能 + gc --auto 环境陷阱
  • 多 CLI 并发互相回退｜ 开工前上下文喂养不足｜ hook 噪声长期带病

二、对策层（增补） ​

  1. 模型名三选一：带 [1m] 后缀 / MAX_CONTEXT_TOKENS / DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT
  2. hooks 三查清单：shell 语义/插件冲突/编码一致性
  3. hook 变更生效：重启会话最稳，配置类变更默认重启验证
  4. 提交慢三查：hook 性能（脚本化替代 shell 循环）/gc 陷阱/锁文件
  5. 并发安全三则：提交前查 WIP/文件级分工/推送后 diff 验证
  6. 真实数据优先：能实测不估算（余额 API/账本/实测）
  7. 上下文工具箱：压缩/裁剪/resume 三选
  8. 开工喂养四段式：背景/决策/状态/边界
  9. hook 噪声=健康度信号：出现即排，消噪只止血
  10. 路径改名三查 + 自愈查 runtime 文件存在性

三、证据层（增补） ​

  • [chunk_06d46abc_000][chunk_322a42f4_000] 模型名窗口坑
  • [chunk_66cf552b_019] hooks 三大坑 ｜ [chunk_a0985ef9_007] 会话缓存
  • [chunk_8c33c5a1_024][chunk_8c33c5a1_014] 提交挂点
  • [chunk_8968e6cf_132] 并发回退 ｜ [chunk_8247daa1_034] 真实数据
  • [chunk_22f6e7ef_001] 手动压缩 ｜ [chunk_38c16180] 上下文喂养
  • [chunk_2e4992d6_001][chunk_4bc2bb55_018] hook 噪声
  • [chunk_a0985ef9_016][chunk_8c33c5a1_038] 路径改名级联

四、优化层（增补） ​

  • 模型名改动检查清单项（改后验证窗口声明）
  • hooks 健康度月度巡检（噪声计数/路径引用）
  • 多会话协作纪律文档化（声明-分工-验证三则）
  • 新会话喂养模板落地（四段式预置）

一、问题层（增补·尾池） ​

  • 多份评估互相引用（锚定效应）｜ 技能库无来源审计
  • 改动前不读项目规范｜ 提醒机制堆叠不可靠
  • 部署验证只信本地（字节矛盾）｜ 测试全过但 GBK 掩盖真问题
  • Hook 安装不完整｜ API 参数格式 400｜ 换机配置无清单｜ 需求中途升级

二、对策层（增补） ​

  1. 独立评估纪律：先写独立判断再读他人方案（b8021964_018）
  2. 技能来源审计三查：来源/90天使用/重复（543bfd6b_001）
  3. 开发规范纪律：改代码前先读 DEV.md，按规范实施（1404136d_010）
  4. 提醒三层可靠性：服务端响应>进程>兜底；消除>提醒（32b5cd5f_058）
  5. 部署验证字节级比对：本地 vs 线上大小/校验和（6893306d_059）
  6. 测试验收加输出结构断言：字段完整性防 GBK 掩盖（b8021964_032）
  7. Hook 安装自验证目标存在性（7dd4692a_065）
  8. API 400=结构问题 422=值问题，首查官方 schema（e767dd47）
  9. 换机配置清单化：每项带「为什么」（e767dd47）
  10. 需求升级三问：范围/原方案/重新探测（3e087333_022）

三、证据层（增补） ​

  • [chunk_b8021964_018] 独立评估 ｜ [chunk_543bfd6b_001] 技能审计
  • [chunk_1404136d_010] 规范纪律 ｜ [chunk_32b5cd5f_058] 提醒三层
  • [chunk_6893306d_059] 字节矛盾 ｜ [chunk_b8021964_032] 测试真问题
  • [chunk_7dd4692a_065] Hook 不完整 ｜ [chunk_e767dd47] API 400
  • [chunk_3e087333_022] 需求升级

四、优化层（增补） ​

  • 尾池经验密度 12%（223 片 → 27 片有效）——claude_habits 池收官判定
  • 独立判断先行的评估流程模板
  • 字节级部署验证挂 deploy 流程
  • 换机配置清单维护（复刻手册联动）

由 site_gen.py 自动生成 — 修改请在本地 txt 源操作