🔍 Claude Code User Documentation Review - 2026-03-30

[github-actions[bot]]

Executive Summary

gh-aw documentation is well-structured for Claude Code users — Claude is presented as a first-class engine alongside Copilot from the very first step of Quick Start. No critical blockers exist for a developer who uses Claude Code exclusively. The 4 minor issues identified yesterday remain unfixed (day 2 persistent), and today's glossary update (e4eade4) did not address them.

Key Finding: Claude Code users can successfully adopt gh-aw today, with minimal friction. The add-wizard flow explicitly offers Claude as an engine choice, authentication docs are complete, and 36 example workflows use engine: claude.

---

Persona Context

I reviewed this documentation as a developer who:

• ✅ Uses GitHub for version control
• ✅ Uses Claude Code as primary AI assistant
• ❌ Does NOT use GitHub Copilot
• ❌ Does NOT use Copilot CLI
• ❌ Does NOT have Copilot subscription

---

Question 1: Onboarding Experience

Can a Claude Code user understand and get started with gh-aw?

Yes, with minimal friction. The Quick Start prerequisites (docs/src/content/docs/setup/quick-start.mdx:29) explicitly lists:

AI Account - GitHub Copilot, Anthropic Claude, or OpenAI Codex

The add-wizard interactive flow (quick-start.mdx:67) tells users to "Select an AI Engine - Choose between Copilot, Claude, or Codex." The tool will prompt for ANTHROPIC_API_KEY automatically if Claude is selected.

Specific Issues Found:

• quick-start.mdx:29 — Gemini is listed as a supported engine in engines.md and auth.mdx but is missing from the prerequisites list (4 engines exist: Copilot, Claude, Codex, Gemini)
• engines.md:17 — Link to Claude product page uses outdated URL www.anthropic.com/index/claude (that path no longer resolves correctly)

Recommended Fixes:

• Add Gemini to the Quick Start prerequisites bullet alongside the other three engines
• Update the Claude product link in engines.md to https://www.anthropic.com/claude

---

Question 2: Inaccessible Features for Non-Copilot Users

What features or steps don't work without Copilot?

Features That Require Copilot (clearly documented):

• max-continuations — Copilot-only autopilot multi-run feature (engines.md feature comparison table)
• engine.agent — Custom .github/agents/ file for customized Copilot system prompts (engines.md:33)
• COPILOT_GITHUB_TOKEN — Copilot-specific PAT requirement

Features That Work Without Copilot (engine-agnostic):

• All built-in tools: edit, github, bash, web-fetch, playwright, cache-memory, repo-memory, qmd, agentic-workflows
• All custom MCP servers
• safe-outputs system (create-issue, create-pr, create-comment, etc.)
• gh aw compile, gh aw run, gh aw logs, gh aw audit, gh aw trial
• max-turns (Claude-only, for turn limiting)

Missing Documentation:

• The web search guide (guides/web-search.md) only shows a Copilot example for MCP-based web search. Since Claude uses the same MCP approach (via MCP in engines feature table), a Claude-specific example would reduce friction.

---

Question 3: Documentation Gaps and Assumptions

Where does the documentation assume Copilot usage?

The docs do not broadly assume Copilot. The main assumption areas are:

Language that could mislead:

• how-they-work.mdx:26 — "Workflows support GitHub Copilot (default), Claude by Anthropic, and Codex." Leading with "default" is accurate but could cause a Claude user to skim past the engine options.
• auth.mdx (CLI example) — gh aw secrets set COPILOT_GITHUB_TOKEN is shown as the primary CLI example, with Claude/Codex/Gemini shown below. Low risk since section headings are clear.

Missing Alternative Instructions:

• guides/web-search.md — Full code example only shows engine: copilot. Claude users would need to swap in engine: claude themselves, which works, but it's not shown.

---

Severity-Categorized Findings

🚫 Critical Blockers (Score: 0)

None. Claude Code users face no absolute blockers.

⚠️ Major Obstacles (Score: 1)

Obstacle 1: Web Search Guide Has No Claude Example

Impact: Claude users adding web search must mentally translate the only example, which uses engine: copilot

Current State: docs/src/content/docs/guides/web-search.md shows a single code block:

engine: copilot
mcp-servers:
  tavily: ...
```

**Why It's Problematic:** The engine field can simply be changed to `claude`, but the guide gives no indication this works identically. A new Claude Code user might wonder if Tavily MCP is Copilot-specific.

**Suggested Fix:** Add a second example or a note: *"Replace `engine: copilot` with `engine: claude` or `engine: codex` — MCP-based web search works identically across all engines."*

**Affected Files:** `docs/src/content/docs/guides/web-search.md`

</details>

#### 💡 Minor Confusion Points (Score: 4)

- **Issue 1: Gemini missing from Quick Start prerequisites** — `docs/src/content/docs/setup/quick-start.mdx:29` lists 3 engines but `engines.md` and `auth.mdx` document 4 (Copilot, Claude, Codex, Gemini) [**PERSISTENT - day 2**]
- **Issue 2: Outdated Claude product URL** — `docs/src/content/docs/reference/engines.md:17` links to `https://www.anthropic.com/index/claude` which is a stale path [**PERSISTENT - day 2**]
- **Issue 3: ANTHROPIC_API_KEY setup URL** — `docs/src/content/docs/reference/auth.mdx:103` directs users to `(platform.claude.com/redacted) (a docs overview page). Direct link to API key creation (`https://console.anthropic.com/settings/keys`) would reduce clicks, similar to how Copilot's setup links directly to the PAT creation page with pre-filled fields [**PERSISTENT - day 2**]
- **Issue 4: Web search guide Copilot-only example** — Downgraded from major to minor because the fix is trivially obvious (swap `engine:` field), but it still represents a gap [**PERSISTENT - day 2**]

---

### Engine Comparison Analysis

#### Available Engines

Based on my review, gh-aw supports 4 engines:

| Engine | Setup Docs | Examples | Auth Docs | Overall Score |
|--------|-----------|----------|-----------|---------------|
| Copilot | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ |
| Claude | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ |
| Codex | ⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐½ |
| Gemini | ⭐⭐⭐ | ⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐ |

Claude scores one star below Copilot primarily due to fewer guide examples and the API key URL friction.

---

### Tool Availability Analysis

**Engine-Agnostic Tools (confirmed):**
- `edit`, `bash`, `web-fetch`, `github` (all toolsets), `playwright`, `cache-memory`, `repo-memory`, `qmd`, `agentic-workflows`, custom `mcp-servers`

**Engine-Specific Tools:**
- `web-search: native` — Codex only (built-in); all other engines use MCP-based web search
- `engine.agent` — Copilot only (custom agent file)
- `max-continuations` — Copilot only
- `max-turns` — Claude only

**Unclear/Undocumented:** None identified.

---

### Authentication Requirements

| Engine | Secret | Setup URL Quality |
|--------|--------|-------------------|
| Copilot | `COPILOT_GITHUB_TOKEN` | ✅ Direct link with pre-filled PAT creation |
| Claude | `ANTHROPIC_API_KEY` | ⚠️ Links to docs page, not API key creation |
| Codex | `OPENAI_API_KEY` | ✅ Direct link to API keys page |
| Gemini | `GEMINI_API_KEY` | ✅ Direct link to AI Studio API keys |

**Missing for Claude Users:** Direct link to `https://console.anthropic.com/settings/keys` in `auth.mdx:103`

---

### Example Workflow Analysis

```
Engine: copilot  — 88 workflows (.github/workflows/)
Engine: claude   — 36 workflows (.github/workflows/)
Engine: codex    — 18 workflows (.github/workflows/)
Engine: gemini   —  <5 workflows

Note: Workflow counts in this repo reflect the gh-aw team's internal usage, not a representative sample. Claude has strong representation (36 files) across diverse use cases: daily reports, security scanning, PR analysis, doc maintenance, schema checking.

Claude Examples Quality: Good. Workflows like audit-workflows.md, daily-doc-updater.md, claude-code-user-docs-review.md demonstrate real-world Claude usage patterns across scheduling, safe-outputs, MCP tools, and repo-memory.

---

Recommended Actions

Priority 1: Quick Wins (all 1-line fixes)

1. Fix Gemini omission in Quick Start prerequisites — Add [Google Gemini]((aistudio.google.com/redacted) to quick-start.mdx:29— File:docs/src/content/docs/setup/quick-start.mdx`
2. Fix outdated Claude URL in engines table — Change https://www.anthropic.com/index/claude to https://www.anthropic.com/claude — File: docs/src/content/docs/reference/engines.md:17
3. Improve ANTHROPIC_API_KEY setup link — Change (platform.claude.com/redacted) to https://console.anthropic.com/settings/keys` — File: docs/src/content/docs/reference/auth.mdx:103

Priority 2: Small Content Addition

4. Add Claude/engine-agnostic note to web search guide — Add one sentence noting all engines can use MCP-based web search by changing the engine: field — File: docs/src/content/docs/guides/web-search.md

Priority 3: Nice-to-Have

5. Add a Claude-specific quick start path — Blog post or guide showing a Claude-only onboarding journey for users who've never touched Copilot
6. Add "engine parity" summary box — A visible callout in how-they-work.mdx summarizing which features are engine-specific vs universal

---

Positive Findings

• ✅ Quick Start is engine-neutral — Claude is explicitly called out in prerequisites and the add-wizard wizard flow
• ✅ Authentication docs are comprehensive — auth.mdx clearly documents all 4 engine secrets with setup steps
• ✅ Engine feature comparison table — engines.md has a clear table showing what's supported per engine (rare in AI tooling docs)
• ✅ 36 real Claude workflow examples — Demonstrates the team actually uses Claude and the examples are production-quality
• ✅ gh aw new --engine claude — CLI scaffolding bakes Claude into the frontmatter template
• ✅ gh aw secrets bootstrap --engine claude — Engine-specific secret management CLI
• ✅ Custom Anthropic endpoint documentation — ANTHROPIC_BASE_URL and anthropic-proxy patterns are documented for enterprise users

---

Conclusion

Can Claude Code Users Successfully Adopt gh-aw?

Answer: Yes

The documentation treats Claude as a first-class engine. The Quick Start wizard, authentication reference, CLI tooling, and engine reference all explicitly support Claude without requiring Copilot. A developer who has never used GitHub Copilot can follow the Quick Start end-to-end and have a Claude-powered agentic workflow running.

The 4 persistent issues are all minor quality improvements, not adoption blockers. The most impactful fix would be updating the ANTHROPIC_API_KEY setup URL to point directly at the API key creation page — this reduces friction at the most critical setup moment.

Overall Assessment Score: 8/10

Dimension	Score
Clarity for non-Copilot users	8/10
Claude engine documentation	8/10
Alternative approaches provided	9/10
Engine parity	8/10

Trend vs. 2026-03-29: No change (score stable at 8/10, same 4 issues persist, no new issues found, glossary-only doc change today)

---

Appendix: Files Reviewed

Complete List of Documentation Files Analyzed

• README.md
• docs/src/content/docs/setup/quick-start.mdx
• docs/src/content/docs/introduction/how-they-work.mdx
• docs/src/content/docs/reference/engines.md
• docs/src/content/docs/reference/tools.md
• docs/src/content/docs/reference/auth.mdx
• docs/src/content/docs/setup/cli.md
• docs/src/content/docs/guides/web-search.md
• .github/workflows/audit-workflows.md (Claude example)
• .github/workflows/claude-code-user-docs-review.md (this workflow's own frontmatter)

---

References: §23746552250

AI generated by Claude Code User Documentation Review · history

• expires on Mar 31, 2026, 1:20 PM UTC

[github-actions[bot]]

This discussion has been marked as outdated by Claude Code User Documentation Review.

A newer discussion is available at Discussion #23722.