Troubleshooting

故障排查

ai-coding-ok 常见问题、症状、原因和修复方法。

---

快速参考

症状	可能原因	修复
AI 不读记忆文件	CLAUDE.md 缺失或 PDCA 强制要求被删	检查 CLAUDE.md，重新安装
Act 阶段不更新记忆	Stop hook 未配置	检查 .claude/settings.local.json
文件中残留 {{占位符}}	安装未完成	重新运行 customize-prompt 或安装
升级后文件损坏	升级时合并冲突	回退后重新升级并仔细审查
Hook 冲突	settings.json 和 settings.local.json 都有 hooks	合并到 settings.local.json
CI 记忆检查总是失败	fetch-depth 太浅	设置 fetch-depth: 0
AI 在 Copilot 上跳过 PDCA	copilot-instructions.md 缺失	重新运行安装
记忆文件过大	未归档	归档旧 task-history 条目

---

安装问题

"缺少必需文件"（verify.sh 退出码 1）

症状： verify.sh 报告缺少文件。

修复：

# 重新运行安装
install ai-coding-ok
# 或手动：
bash install.sh --copilot --target /path/to/project

"未填充占位符"（verify.sh 退出码 2）

症状： {{项目名称}} 或 {{语言}} 仍在文件中。

修复：

• Claude Code： install ai-coding-ok（AI 会检测已有文件并提供重新定制）
• Copilot： 重新粘贴 scripts/customize-prompt.md 到 Copilot Chat

---

PDCA 触发问题

"AI 编码前不读记忆"

检查清单：

1. CLAUDE.md 是否存在且包含 @AGENTS.md？
2. AGENTS.md 顶部是否有 PDCA 强制要求块？
3. .github/agent/memory/ 目录是否存在？
4. 记忆文件是否已填充（非空）？

修复：

# 快速修复：手动提醒 AI
先读取 .github/agent/memory/project-memory.md 和 task-history.md 再继续。

# 永久修复：重新安装 CLAUDE.md
install ai-coding-ok

"AI 编码后不更新记忆"

症状： 响应中无 ## 记忆更新 章节。

立即修复：

现在执行 Act 阶段：将本次任务摘要写入 task-history.md。

永久修复（Claude Code）：

1. 检查 .claude/settings.local.json 是否存在
2. 验证 Stop hook 已配置
3. 升级到 v4.1.0：upgrade ai-coding-ok

---

升级问题

"升级显示'无需变更'但我是旧版本"

版本标记可能缺失或损坏：

head -1 AGENTS.md
# 如果缺失，手动添加：
echo "<!-- ai-coding-ok: v2.0 -->" | cat - AGENTS.md > temp && mv temp AGENTS.md

"升级后文件损坏"

# 回退升级
git checkout HEAD~1 -- AGENTS.md CLAUDE.md .github/
# 重新升级并仔细审查
upgrade ai-coding-ok

---

Hook 问题（Claude Code）

"Stop hook 总是阻断会话结束"

原因：

• task-history.md 已保存但未 git staged
• Hook 脚本有 bug
• {{SOURCE_DIR_PATTERN}} 错误

修复：

# 检查 task-history.md 是否实际被修改
git diff .github/agent/memory/task-history.md

# 检查 hook 配置
cat .claude/settings.local.json

---

CI 问题

"memory-check 在 PR 上总是失败"

原因： checkout action 中 fetch-depth: 0 未设置。

修复：

- uses: actions/checkout@v4
  with:
    fetch-depth: 0  # ← 必需

---

记忆文件问题

"task-history.md 太大"

# 归档 30 条后的条目
tail -n +31 task-history.md > docs/task-history-archive-$(date +%Y-Q%m).md
head -n 30 task-history.md > temp && mv temp task-history.md

"project-memory.md 有过时信息"

1. 审查 project-memory.md
2. 删除或更新过时章节
3. 将废弃的架构决策以"已废弃"状态移到 decisions-log.md
4. 添加新模块和约束

---

平台特定问题

Copilot："AI 忽略 PDCA 指令"

1. 验证 .github/copilot-instructions.md 存在且有 PDCA 强制执行块
2. 升级到 v3.0.1+（强制记忆更新章节）
3. 手动提醒："按照 .github/copilot-instructions.md 中的指令操作"

Cursor："规则未生效"

1. 检查 .cursor/rules/ai-coding-ok.mdc 是否存在
2. 验证前置元数据有 alwaysApply: true
3. 重启 Cursor 重新加载规则

---

还是卡住了？

• FAQ — 更多常见问题
• GitHub Issues — 报告 bug 或求助
• 五层防御体系 — 理解防御系统
• Hooks 系统 — 详细 hooks 调试