[claude-code-user-docs-review] Claude Code User Documentation Review - 2026-06-07 #37551
Closed
Replies: 1 comment
-
|
This discussion was automatically closed because it expired on 2026-06-08T13:03:55.276Z.
|
Beta Was this translation helpful? Give feedback.
0 replies
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Uh oh!
There was an error while loading. Please reload this page.
-
A Claude Code user can adopt gh-aw today — no hard blockers. Docs are commendably engine-neutral at the top (
README.md:40"pick whichever AI account you already have"). The real friction is subtler: Copilot is the silent default engine, and Claude Code's own OAuth token is explicitly unsupported — a trap unique to this exact persona. Overall: 8/10.Persona Context
Severity Findings
🚫 Critical Blockers — 0 found
No documentation gap fully prevents adoption. Prerequisites (
quick-start.mdx:29) list a generic "AI Account" with Claude as a first-class option; theadd-wizardlets you select Claude (quick-start.mdx:70);ANTHROPIC_API_KEYsetup is documented (quick-start.mdx:84-88); and no tool is Claude-blocked (see Tool Availability). A Claude-only developer can complete the quick start.M1 — Copilot is the silent default engine. The runtime default is
copilot(pkg/constants/engine_constants.go:34,DefaultEngine = CopilotEngine). None of the six core docs state this default or warn that omittingengine:selects Copilot. A Claude user who hand-adds a workflow (skipping the wizard) and forgets the field gets a run that fails for lack ofCOPILOT_GITHUB_TOKEN, with no doc pointing at the cause. Fix: state the default explicitly inquick-start.mdxandhow-they-work.mdx, e.g. "If you omitengine:, Copilot is used — Claude users must setengine: claude."M2 — Claude Code's own OAuth token is unsupported, and the caveat is hidden.
CLAUDE_CODE_OAUTH_TOKENis explicitly not supported and ignored if set; onlyANTHROPIC_API_KEYworks (reference/auth.mdx:121-123). This is the most Claude-Code-specific trap in the project: a Claude Code user's instinct is to reuse the OAuth token theirclaudeCLI already issued — and it silently won't work. The caveat lives only inauth.mdx;quick-start.mdx:71,84-88never mentions it. Fix: add a one-line note to theANTHROPIC_API_KEYcallout in quick-start.M3 — Copilot-first framing in the one shared setup step. In the wizard step,
COPILOT_GITHUB_TOKENis listed first (quick-start.mdx:71) and gets the first, longer NOTE box — a multi-step fine-grained-PAT flow (quick-start.mdx:77-81) — before the simplerANTHROPIC_API_KEYnote (84-88). A Claude reader wades through Copilot-only PAT instructions that don't apply to them. Fix: reorder or tab the callouts per engine.💡 Minor Confusion — 3
m1 — No Claude model-selection guidance. None of the six core docs explain pinning Opus vs Sonnet for
engine: claude; only the bareengine: claudeform is shown (quick-start.mdx:129-133). A Claude Code power user expects model control.m2 — Engine differences buried. Claude's 60s tool timeout (vs Codex 120s) appears only at
reference/tools.md:157, not surfaced during setup.m3 — No "why Claude over Copilot?" / engine-comparison page. The docs let you pick an engine but never compare them, so a Claude user gets no validation that Claude is fully supported.
Engine Comparison
CODEX_API_KEYalt + web-search-disabled-by-default only inauth.mdx/tools.md:67shared/include)Tool Availability
Per
reference/tools.md, 13 of 14 documented tools are engine-agnostic; onlyweb-searchis engine-dependent.edit,github,bash,web-fetch,playwright,cache-memory,repo-memory,qmd,agentic-workflows,cli-proxy,mcp-servers,tools.timeout,tools.startup-timeoutweb-searchtools.md:62,67)agentic-workflows,playwright,github→ engine-agnostic ✅ (answers the parity question directly)copilotintools.md; Copilot is not a tool, only an engine. 0 Claude-only and 0 Copilot-only tools — strong tool parity for Claude users.Authentication Gaps
ANTHROPIC_API_KEYCLAUDE_CODE_OAUTH_TOKENunsupported caveat absent from quick-start (M2); no API-key validation/troubleshooting beyond generic FAQ linksCOPILOT_GITHUB_TOKEN(fine-grained PAT; GitHub Apps/OAuth not supported,auth.mdx:95)OPENAI_API_KEY(orCODEX_API_KEY)auth.mdx:143-145Claude auth is documented in
auth.mdx:103-125andquick-start.mdx:84-88— the gap is discoverability from the setup path, not absence.Example Parity
engine: claudeappears in 64 example workflows (.github/workflows/*.md) vs 127 Copilot, 14 Codex, 1 "custom". Claude has a dedicated smoke test (smoke-claude.md) and broad coverage (ci-doctor.md,scout.md,audit-workflows.md). Claude example coverage is healthy — second only to the default engine — so a Claude user has ample patterns to copy.Recommended Actions
Priority 1 (adoption-blocking friction)
copilot) inquick-start.mdx/how-they-work.mdxand warn that omittingengine:fails for Claude users withoutCOPILOT_GITHUB_TOKEN(M1).CLAUDE_CODE_OAUTH_TOKEN-unsupported note to the quick-startANTHROPIC_API_KEYcallout (M2).Priority 2 (reduce confusion)
3. Reorder/tab the secret callouts so Claude users aren't led through Copilot PAT steps first (M3).
4. Add a short "choosing an engine" comparison page, including Claude model-selection (m1, m3).
Priority 3 (polish)
5. Surface per-engine timeout defaults near setup (m2); clarify that "custom" is not a secret-bearing engine; fix internal references to
quick-start.md(the file is.mdx).Conclusion
Can Claude Code users adopt gh-aw? Yes. The docs are genuinely engine-neutral and tool parity is essentially complete (13/14 tools agnostic, 64 Claude examples, full Claude auth docs). The remaining friction is two well-hidden traps — the silent Copilot default and the unsupported Claude Code OAuth token — plus Copilot-first ordering in setup. Fixing the two Priority-1 items would push this to ~9.5/10. Overall: 8/10.
References:
Beta Was this translation helpful? Give feedback.
All reactions