Skip to content

Troubleshooting

Jump to bottom
mark7766 edited this page Jul 14, 2026 · 2 revisions

Troubleshooting

Common issues with ai-coding-ok, their symptoms, causes, and fixes.

Quick reference

Symptom Likely cause Fix
AI doesn't read memory files CLAUDE.md missing or PDCA mandate removed Check CLAUDE.md, re-install
Act phase not updating memory Stop hook not configured Check .claude/settings.local.json
{{placeholders}} in files Installation incomplete Re-run customize-prompt or install
Upgrade corrupted files Merge conflict during upgrade Revert and re-upgrade with review
Hook conflicts settings.json and settings.local.json both have hooks Merge into settings.local.json
CI memory check always fails fetch-depth too shallow Set fetch-depth: 0
AI skips PDCA on Copilot copilot-instructions.md missing Re-run install
Memory files growing too large No archival Archive old task-history entries

Installation issues

"Missing required files" (verify.sh exit 1)

Symptom: verify.sh reports missing files.

Causes:

  • Install script didn't complete
  • Files were accidentally deleted
  • Wrong target directory

Fix:

# Re-run the install
install ai-coding-ok

# Or manually:
bash install.sh --copilot --target /path/to/project

"Unfilled placeholders" (verify.sh exit 2)

Symptom: {{project-name}} or {{语言}} still in files.

Causes:

  • Customization step was skipped
  • AI didn't complete placeholder replacement

Fix:

Claude Code:

install ai-coding-ok
# AI will detect existing files and offer to re-customize

Copilot: Re-paste scripts/customize-prompt.md into Copilot Chat.

"settings.json conflicts with settings.local.json"

Symptom: Installer warns about hook conflicts.

Fix:

  1. Open both files
  2. Copy hooks from settings.json to settings.local.json
  3. Remove hooks from settings.json
  4. Only settings.local.json should have hooks

PDCA triggering issues

"AI doesn't read memory before coding"

Symptom: AI starts coding immediately without reading .github/agent/memory/.

Checklist:

  1. Does CLAUDE.md exist and contain @AGENTS.md?
  2. Does AGENTS.md have the PDCA mandate block at the top?
  3. Does .github/agent/memory/ directory exist?
  4. Are the memory files populated (not empty)?

Fix:

# Quick fix: manually remind the AI
Read .github/agent/memory/project-memory.md and .github/agent/memory/task-history.md before proceeding.

# Permanent fix: re-install CLAUDE.md
# In Claude Code:
install ai-coding-ok

"AI doesn't update memory after coding"

Symptom: No ## Memory Updates section in the response.

Causes:

  • v3.0.0 or earlier (Act enforcement added in v3.0.1)
  • Stop hook not configured (Claude Code)
  • AI in long session, skipped Act

Fix:

Immediate:

Run the Act phase now: update task-history.md with this task's summary.

Permanent (Claude Code):

  1. Check .claude/settings.local.json exists
  2. Verify Stop hook is configured
  3. Upgrade to v3.1.0: upgrade ai-coding-ok

Permanent (Copilot/Cursor): Upgrade to v3.0.1+ for mandatory Memory Updates section.

"AI skips PDCA on simple tasks"

Symptom: AI reads memory for big features but skips for "fix a typo."

Fix: The Five-Layer Defense (v3.1.0) addresses this. Upgrade:

upgrade ai-coding-ok

Or manually remind:

Even for small changes, follow the PDCA workflow. Update task-history.md.

Upgrade issues

"Upgrade says 'no changes needed' but I'm on old version"

Symptom: upgrade ai-coding-ok detects no changes.

Causes:

  • Version markers missing or corrupted
  • Templates already match (unlikely if version is old)

Fix:

# Check version markers
head -1 AGENTS.md
head -1 .github/copilot-instructions.md

# If missing, manually add:
echo "<!-- ai-coding-ok: v2.0 -->" | cat - AGENTS.md > temp && mv temp AGENTS.md

Then retry: upgrade ai-coding-ok

"Upgrade wants to delete my custom section"

Symptom: Upgrade detects a section you added as "should be removed."

Fix: During the interactive upgrade, choose "skip" for that section. The upgrade asks for confirmation before each change.

"Files corrupted after upgrade"

Symptom: After upgrade, some files have mixed content.

Fix:

# Revert the upgrade
git checkout HEAD~1 -- AGENTS.md CLAUDE.md .github/

# Re-run upgrade with careful review
upgrade ai-coding-ok
# Review each change individually

Hook issues (Claude Code)

"Stop hook always blocks session end"

Symptom: Session won't end even after updating memory.

Causes:

  • task-history.md saved but not staged in git
  • Hook script has a bug
  • Wrong {{SOURCE_DIR_PATTERN}}

Fix:

# Check if task-history.md was actually modified
git diff .github/agent/memory/task-history.md

# If modified but not staged:
git add .github/agent/memory/task-history.md

# Check hook configuration
cat .claude/settings.local.json

"PreToolUse blocks legitimate commands"

Symptom: Can't run git push or other legitimate operations.

Fix: Adjust the PreToolUse matcher in .claude/settings.local.json:

{
  "matcher": "Bash",
  "hooks": [{
    "type": "command",
    "command": "bash -c '... less restrictive check ...'"
  }]
}

Or temporarily disable the hook by removing it from the array.

"Hooks slow down Claude Code"

Symptom: Noticeable delay on tool use or session end.

Fix: Ensure hook scripts are lightweight:

  • No network calls
  • No heavy computation
  • git diff only on specific files, not the whole repo

CI issues

"memory-check always fails on PRs"

Symptom: CI reports "task-history.md was NOT updated" on every PR.

Causes:

  • fetch-depth: 0 not set in checkout action
  • Wrong base ref comparison
  • Task-history actually not updated

Fix:

- uses: actions/checkout@v4
  with:
    fetch-depth: 0  # ← Required for git diff against base

"verify.sh not found in CI"

Symptom: CI step fails with "verify.sh: No such file or directory."

Fix: Either commit verify.sh to your project:

cp /path/to/ai-coding-ok/scripts/verify.sh scripts/
git add scripts/verify.sh
git commit -m "chore: add verify.sh for CI"

Or reference the full path to the ai-coding-ok repo in CI.

Memory file issues

"task-history.md is too large"

Symptom: File has 50+ entries, AI takes longer to read.

Fix:

# Archive entries beyond 30
tail -n +31 .github/agent/memory/task-history.md > docs/task-history-archive-$(date +%Y-Q%m).md
head -n 30 .github/agent/memory/task-history.md > temp && mv temp .github/agent/memory/task-history.md

"project-memory.md has stale information"

Symptom: AI references outdated architecture or modules.

Fix:

  1. Review project-memory.md
  2. Remove or update stale sections
  3. Move deprecated architecture decisions to decisions-log.md with "Deprecated" status
  4. Add new modules and constraints

"Decisions log has duplicate ADRs"

Symptom: Two ADRs with the same number or conflicting decisions.

Fix:

  1. Renumber the newer one to a new number
  2. If they conflict, mark the older one as "Superseded" with a reference to the newer one
  3. Add a note in the newer one: "Supersedes ADR-XXX"

Platform-specific issues

Copilot: "AI ignores PDCA instructions"

Symptom: Copilot doesn't read memory files or update task-history.

Fix:

  1. Verify .github/copilot-instructions.md exists and has the PDCA enforcement block
  2. Upgrade to v3.0.1+ (mandatory Memory Updates section)
  3. Manually remind: "Follow the instructions in .github/copilot-instructions.md"

Cursor: "Rules not applying"

Symptom: Cursor doesn't follow PDCA workflow.

Fix:

  1. Check .cursor/rules/ai-coding-ok.mdc exists
  2. Verify it has alwaysApply: true in frontmatter
  3. Restart Cursor to reload rules

Still stuck?

🧠 ai-coding-ok — AI 编程的 PDCA 记忆闭环。
GitHub · Issues · MIT License

🧠 ai-coding-ok

🏠 首页

📖 快速上手

🧠 核心概念

📘 使用指南

🏗️ 架构

🔧 高级

📋 参考

GitHub 仓库

Clone this wiki locally