Claude Code

Summary

Claude Code is used across the workspace project as the primary runtime for agentic AI workflows — specifically a Strategy Agent that orchestrates 10-step competitive analysis pipelines, and a suite of audit skills (SEO, responsive, Google Ads, robots) that run against client sites. The most recurring failure mode is third-party API field name mismatches: SpyFu, Moz, and DataForSEO have all required fixes for wrong parameter names or response path assumptions. Audit skills require a mandatory MD-to-PDF conversion before Slack delivery, and all commands should be hardened with pre-flight validation before main execution. The .claude/commands/ and .claude/skills/ directories are now tracked in git (they contain no secrets), while the rest of .claude/ remains ignored.

TL;DR

What we've learned
- Third-party SEO APIs (SpyFu, Moz, DataForSEO) consistently have wrong field names on first integration — budget time for a fix pass after every new API addition
- All audit skills must convert output to PDF before posting to Slack; skipping this step breaks delivery
- Hardcoded paths (D:\...) and inline Python scripts in audit commands break on non-Windows environments; replace with {CWD} placeholders and MCP tool calls
- The .claude/commands/ and .claude/skills/ directories should be tracked in git — they're reusable procedures with no secrets, and losing them to .gitignore is a real cost
- Google's urn:ietf:wg:oauth:2.0:oob OAuth flow was deprecated in 2022 and will silently fail in any new Google MCP integration

External insights

No external sources ingested yet for this topic.

Common Failure Modes

SpyFu API: wrong endpoint and wrong parameter name

SpyFu's keyword tool was called against a non-existent endpoint (getKeywordRankings) and passed query as the parameter name. Both are wrong. The correct endpoint is getKeywordInformation, and the parameter must be Keywords with a capital K.

# Wrong
spyfu.getKeywordRankings(query="atm machine")

# Correct
spyfu.getKeywordInformation(Keywords="atm machine")

This produced silent failures — the tool returned no results rather than an error. Observed in the workspace project during competitive intelligence work for clients including BluePoint ATM and Citrus America.
^[1]

Moz API: wrong field names in url_metrics and link_intersect

Two separate Moz failures in the workspace project:

1. url_metrics field mapping: The fields linking_root_domains and external_links don't exist in the response. The correct fields are root_domains_to_root_domain and external_pages_to_root_domain.

2. link_intersect limit: The API has a hard limit of 100-200 results; requests above that threshold were failing. Reduced to 50 to stay safely under the limit.

3. link_intersect URL format: sourcePage URLs missing the protocol prefix (https://) caused silent failures. The tool now normalizes URLs before sending.

All three were observed in the workspace project, with Adava Care as the client context for the field mapping fix.
^[2]

DataForSEO: wrong response path assumption

dfs_search_volume was returning no results because the response parser assumed keyword objects lived at result.data[0]. They actually live at tasks[0].result as a direct array.

# Wrong assumption
keywords = response["result"]["data"][0]

# Correct
keywords = response["tasks"][0]["result"]

Observed in the workspace project.
^[3]

Google Docs MCP: deprecated OAuth flow and broken table rendering

Two distinct failures in the Google Docs MCP:

1. OAuth: The urn:ietf:wg:oauth:2.0:oob redirect URI flow was deprecated by Google in 2022. Any new Google MCP integration using this flow will fail at the auth step. Fix: use http://localhost redirect URI.

2. Table rendering: The Docs API batchUpdate method doesn't render Markdown tables correctly. Fix: switched to Drive API HTML upload, which preserves table structure.

Both observed in the workspace project.
^[4]

Google Ads audit skill: hardcoded paths and broken credential loading

The Google Ads audit skill had three compounding failures:

1. Hardcoded D:\... Windows paths broke in Git Bash and on non-Windows environments. Fix: replace with {CWD} placeholders.
2. .env file loading for credentials failed in Claude Code's execution context. Fix: read credentials from .mcp.json instead.
3. Inline Python scripts for GSC and GA4 data were fragile and platform-dependent. Fix: replaced with MCP tool calls (seo_search_performance, g_ga4_traffic_sources).

Observed in the workspace project.
^[5]

Coolify MCP: no service logs endpoint in the API

The Coolify API has no endpoint for fetching service logs. Attempting to retrieve logs through the API returns nothing useful. The fix is to fetch container logs via SSH directly.

# Coolify API: no logs endpoint — use SSH instead
ssh user@host "docker logs <container_id> --tail 100"

Observed in the workspace project when building the Coolify MCP server.
^[6]

Channel detection missing active campaigns in non-standard folder paths

The channel detection logic scanned the Strategy Agent date folder for campaign files. Clients like BluePoint ATM and Citrus America had active campaigns stored in 06_Projects/07_Projects/ folders in Google Drive, which the scanner never reached. Fix: extend channel detection to scan Google Drive project folder paths in addition to the local date folder.
^[7]

What Works

Pre-flight validation before audit execution

Audit commands that run pre-flight checks before the main workflow catch environment failures early rather than mid-run. The robots audit command implements a Step 0 that validates: SSH access, CF-RAY header presence (confirming Cloudflare is active), GSC credentials, and site reachability. This pattern has been applied to the robots audit and Google Ads audit in the workspace project and is worth applying to every new audit skill.
^[8]

MCP tool calls instead of inline scripts

Replacing inline Python scripts and node -e one-liners with MCP tool calls has consistently improved reliability and cross-platform compatibility. The Google Ads audit skill migration from Python GSC/GA4 scripts to seo_search_performance and g_ga4_traffic_sources MCP calls is the clearest example. MCP tools also benefit from the credential management that's already wired into .mcp.json, avoiding the .env loading failures that inline scripts hit.
^[9]

Tracking .claude/commands/ and .claude/skills/ in git

The default .gitignore pattern for Claude Code projects excludes all of .claude/. Commands and skills in .claude/commands/ and .claude/skills/ contain no secrets — they're reusable audit procedures — and should be tracked. The workspace project explicitly un-ignores these paths. Without this, audit skill improvements are lost between machines and contributors.

# In .gitignore — un-ignore commands and skills
!.claude/commands/
!.claude/skills/

^[10]

Date-folder storage with automatic most-recent discovery

Organizing strategy output under YYYY-MM-DD/ date folders per client, then having the Strategy Agent automatically discover and load the most recent prior run as Step 0 context, gives the agent continuity across runs without manual wiring. The workspace project uses this for all 31 active clients. The pattern also makes it easy to audit what was generated on any given date.
^[11]

client-map.json as authoritative configuration source

Extending client-map.json from a simple slug-to-name mapping to rich objects (industry, goal, model, geo, location, size, budget, competitors, channels, CMS) for all 31 active clients gives every tool a single source of truth for client context. The competitor generator uses it to avoid hallucinating extra competitors when known ones are provided. Channel detection reads it for expected channel types. This pattern reduces the number of places client configuration lives.
^[12]

Documentation hooks in Claude Code projects

In hazardos, Claude Code hooks were added to fire documentation reminders alongside code changes. This is a lightweight enforcement mechanism — the hook doesn't block commits, but it surfaces the reminder at the moment the change is made. Single-project finding so far, but the pattern is worth replicating in any project where documentation drift is a problem.
^[13]

Gotchas and Edge Cases

Competitor generator over-generates when known competitors exist. The auto-generate-from-profile logic will add competitors beyond the known list if not explicitly constrained. When client-map.json has verified competitor domains, the generator must be told to use only those — no extras. This was tightened in the workspace project after Adava Care's competitor list grew unexpectedly.
^[14]

PDF delivery is mandatory for all audit skills, not optional. The MD-to-PDF conversion step was added retroactively across all audit skills after some were posting raw Markdown to Slack. This is now enforced as a convention: every audit skill must convert to PDF before posting. There is no Slack-posting path that bypasses PDF generation.
^[15]

Only Channel Strategy and OKR reports go to Slack. The strategy_run_full orchestration runs 10 steps and generates multiple reports. Of those, only the Channel Strategy and OKR reports are posted to Slack. Everything else is saved to results/strategy/ for reference. This is intentional — not a bug — but it's easy to assume all reports get posted.
^[16]

about.md is not always present; fall back to client-profile.md. The strategy_client_profile tool originally assumed about.md existed for every client. It doesn't. The fallback to client-profile.md was added after silent failures when the file was missing. Any tool reading client profile data should implement this fallback.
^[17]

CloudFlare zone lookup must be dynamic, not credential-sheet-based. The robots audit previously verified Cloudflare presence by trusting a credentials sheet. This was replaced with a live CF-RAY header check plus dynamic zone lookup by domain. The credentials sheet can be stale; the CF-RAY header cannot lie.
^[18]

Hardcoded credentials in ABM Factory scripts. The ABM Factory had hardcoded credentials that were removed and replaced with environment variable fallbacks. Any script that runs in Claude Code's execution context should source credentials from environment variables or .mcp.json, not from inline strings or .env files.
^[19]

Where Docs Disagree With Practice

Coolify API docs imply log access; the API has no logs endpoint. The Coolify API documentation covers service management broadly, but there is no endpoint for container logs. In practice (workspace project), logs must be fetched via SSH with docker logs. Plan for this when building any Coolify MCP tool that needs observability.
^[6]

Google Docs API batchUpdate appears to support rich content; tables don't render. The Docs API accepts Markdown-like content via batchUpdate, but table structures don't survive the conversion. The Drive API HTML upload path is the only reliable way to get tables into a Google Doc from generated Markdown. This isn't documented as a limitation — you discover it when your tables arrive as plain text.
^[20]

Google OAuth docs still reference the oob flow in some older guides. The urn:ietf:wg:oauth:2.0:oob out-of-band flow was deprecated in 2022, but older Google developer documentation and many third-party tutorials still show it. Any guide written before mid-2022 that uses this redirect URI is describing a flow that no longer works.
^[21]

Tool and Version Notes

Moz link_intersect: Hard limit of 100-200 results; requests above this fail silently. Use a limit of 50 or below for reliable results. Field names in url_metrics responses are root_domains_to_root_domain and external_pages_to_root_domain — not the more intuitive names you might guess.

SpyFu API: Endpoint is getKeywordInformation (not getKeywordRankings). Parameter is Keywords with capital K (not query). Both wrong names produce no error, just empty results.

DataForSEO search_volume: Response structure is tasks[0].result[] (array directly on result), not result.data[0]. Confirmed in workspace project.

Google Docs MCP: Requires http://localhost redirect URI for OAuth. Drive API HTML upload is the correct path for Markdown-with-tables content.

Coolify MCP: Built in workspace project. Covers apps, services, databases, deployments, env vars. No native log access — SSH required for container logs.

Google MCP server: 17 tools across GA4, GTM, and Google Ads, added in a single 24-file commit (+6714 lines). CloudFlare auth migrated from X-Auth-Email/X-Auth-Key headers to Bearer token sourced from environment variables.

DataForSEO + Frase + LLMRefs MCP servers: Added together — DataForSEO (9 tools), Frase (4 tools), LLMRefs (6 tools) — in a 61-file commit (+10,556 lines).

Related Topics

Sources

Synthesized from 32 fragments: 31 git commits across workspace, eydn-app, hazardos, adava-care, bluepoint-atm, citrus-america, colorado-atm-company, and papertube projects; 0 external sources; 0 post-mortems. Date range: unknown to unknown.