AI Coding troubleshooting: locating and fixing high-frequency failures
The most common production failures for AI Coding and their root-cause fixes.
On this page
Quick answer
What is the difference between Claude Code and Cursor rules file formats?
Both use CLAUDE.md or .cursorrules to pin hard constraints (stack, package manager, prohibitions). The file formats differ slightly — do not mix them.
Machine-readable page data: /data/ai-coding-troubleshooting.json
In-depth analysis
AI Coding (Vibe Coding) uses agents like Claude Code, Cursor, and v0 to assist development: first encode the hard constraints in a rules file, then let the model produce runnable code inside that controlled context. Troubleshoot by three layers — build, deploy, runtime — diagnose by symptom, never blind-trial.
# .cursorrules / CLAUDE.md — hard constraints for the coding agent (context tightening)
stack: Astro + Tailwind v4 + Cloudflare Pages (output: static)
package: pnpm only, lockfile committed, --frozen-lockfile in CI
secrets: always use the placeholder <CF_API_TOKEN>, never paste real values into code or conversation
comments: no Chinese in code or comments
# One-command scaffold
npx create-astro@latest my-site --template minimal --no-install
cd my-site && pnpm install && pnpm devAI Coding Troubleshooting · Key takeaways
- Build, deploy, or runtime layer identified
- Relevant logs and status codes captured
- Fix verified and reproducible
- Fix notes recorded for reuse
FAQ & pitfalls
What is the risk of pasting secrets into a prompt?
Secrets echo back through the conversation context and leak. Always use the placeholder <CF_API_TOKEN>; real values live only in the Cloudflare / Pages dashboard.
How do I keep AI-generated code from poisoning build cache?
Put rules and lockfiles under version control; CI uses --frozen-lockfile. Generated output goes to an isolated branch so it never pollutes main branch builds.
Explore the hub
See all 5 guides in AI AgentsSame category as this article, sorted across the codebase.
AEO architecture: layered patterns for high-concurrency edge apps
The edge-delivery view of AEO's layering and data flow.
AEO best practices: engineering conventions for production
Field-tested AEO practices from production, avoiding the common anti-patterns.
AEO deployment guide: zero-ops edge publishing with Cloudflare Pages
Git-driven AEO deployment in practice: commit to build, atomic publish to every edge node.
AEO engineering practice: a full guide from architecture to production
Production architecture and core pain points for AEO.
Share & save
What readers are asking
Questions that keep coming back in reader feedback, already answered.
- 01
Why is my Astro component's interactivity not working?
Components ship as zero-JS HTML by default, so an interactive one needs a client:* directive (client:load, client:visible, …). Without it the script is never bundled into the page.
See the full guide → - 02
Why is my custom Tailwind v4 brand colour not applied?
Colours must be declared in @theme (for example --color-brand). A missing @tailwindcss/vite plugin, or a leftover v3 config, makes bg-brand silently render nothing.
See the full guide → - 03
Why are _headers / _redirects not taking effect?
Both files must sit at the root of the output directory (dist/); anything under src/ is never uploaded. A purely static project should not add _worker.js either — that gives up the zero-cold-start advantage.
See the full guide →