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

[github-actions[bot]]

Executive Summary

For the third consecutive day, this review confirms that Claude Code users can successfully adopt gh-aw without critical blockers. The Quick Start guide presents Claude as a first-class AI engine alongside Copilot, authentication documentation is comprehensive, and 35 Claude-engine example workflows exist in the repository. However, four documentation issues identified on day 1 remain unaddressed after three review cycles — the most important being a broken API key setup link and missing Claude/Gemini examples in the web search guide.

Key Finding: No changes since yesterday's review. Overall score holds at 8/10. Four persistent issues need attention before they become accepted as permanent documentation debt.

---

Persona Context

This documentation was reviewed 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

---

Day-Over-Day Comparison

Metric	2026-03-29	2026-03-30	2026-03-31
Overall Score	8/10	8/10	8/10
Critical Blockers	0	0	0
Major Obstacles	1	1	1
Minor Issues	4	4	4
Claude Workflows	36	36	35
Fixes Applied	—	0	0

No documentation issues have been fixed across 3 review cycles. The workflow count dropped by 1 for both claude and copilot engines (natural variation; no documentation impact).

---

Question 1: Onboarding Experience

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

Yes, with good clarity. The Quick Start guide (docs/src/content/docs/setup/quick-start.mdx) explicitly lists Claude in prerequisites:

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

The interactive gh aw add-wizard command is described as guiding users to "Select an AI Engine - Choose between Copilot, Claude, or Codex," and Step 3 explicitly documents that users need either COPILOT_GITHUB_TOKEN, ANTHROPIC_API_KEY, or OPENAI_API_KEY. The How It Works page (docs/src/content/docs/introduction/how-they-work.mdx) states:

"Workflows support GitHub Copilot (default), Claude by Anthropic, and Codex."

Specific Issues Found:

• Gemini missing from Quick Start prerequisites and add-wizard description — docs/src/content/docs/setup/quick-start.mdx, Prerequisites section and Step 3. Gemini is a supported engine (with GEMINI_API_KEY) but is absent from the onboarding path. Users who come to the tool specifically to use Gemini would not find setup instructions in the Quick Start.
• Copilot-as-default framing — docs/src/content/docs/introduction/how-they-work.mdx says Copilot is "default." This is technically accurate but can imply preferential support. The engines reference clearly documents all engines as equal citizens.

Recommended Fixes:

• Add Gemini to Quick Start prerequisites: "GitHub Copilot, Anthropic Claude, OpenAI Codex, or Google Gemini"
• Update Step 3 in Quick Start to include GEMINI_API_KEY alongside the other three secrets
• Update add-wizard description to mention all four engines

---

Question 2: Inaccessible Features for Non-Copilot Users

What features or steps don't work without Copilot?

Features That Require Copilot

Feature	Documentation Location	Notes
max-continuations	docs/src/content/docs/reference/engines.md line 30	Autopilot/multi-run mode; Copilot only
engine.agent (custom agent files)	docs/src/content/docs/reference/engines.md line 33	.github/agents/ file support; Copilot only
Assigning Copilot coding agent to issues/PRs	docs/src/content/docs/reference/auth.mdx line 36	Safe outputs feature

These are clearly documented in the Engine Feature Comparison table at docs/src/content/docs/reference/engines.md lines 27-36.

Features That Work Without Copilot (Engine-Agnostic)

All tools are engine-agnostic unless noted:

• tools.edit — file editing
• tools.github — full GitHub API toolset
• tools.bash — shell command execution
• tools.web-fetch — web content fetching (all engines)
• tools.playwright — browser automation
• tools.cache-memory / tools.repo-memory — persistent memory
• tools.agentic-workflows — workflow introspection
• Custom MCP servers (mcp-servers:) — all engines
• Safe outputs (create issues, comments, PRs) — all engines
• max-turns — Claude only, but documented

Missing Documentation:

• The web-search guide (docs/src/content/docs/guides/web-search.md) only shows a Copilot engine example. Claude and Codex both support web search via MCP, but there are no non-Copilot examples provided.

---

Question 3: Documentation Gaps and Assumptions

Where does the documentation assume Copilot usage?

Copilot-Centric Language Found

• File: docs/src/content/docs/introduction/how-they-work.mdx — States "GitHub Copilot (default)" which correctly notes the default but could imply Copilot is the primary/preferred engine
• File: docs/src/content/docs/guides/web-search.md line 17 — Example workflow hardcoded with engine: copilot, with no Claude/Codex alternatives shown
• File: docs/src/content/docs/reference/engines.md line 21 — "Copilot CLI is the default — engine: can be omitted when using Copilot." This is accurate but could confuse users who want the default to be Claude
• File: docs/src/content/docs/reference/auth.mdx line 48 — The CLI example under "Adding secrets using the CLI" only shows COPILOT_GITHUB_TOKEN, not a Claude example

Missing Alternative Instructions:

• No Claude-specific example in the web search guide (requires Tavily MCP setup, which is engine-agnostic, but the example doesn't show this for Claude)
• No "switching engines" guide for users migrating from another tool or starting fresh with Claude

---

Severity-Categorized Findings

🚫 Critical Blockers (Score: 0)

None found. A Claude Code user can successfully complete the Quick Start guide and run workflows.

⚠️ Major Obstacles (Score: 1)

Obstacle 1: ANTHROPIC_API_KEY Setup URL Points to Docs Page (Day 3 - Persistent)

Impact: Friction during onboarding — user lands on a documentation page instead of the API key creation console

Current State: docs/src/content/docs/reference/auth.mdx line 103:

Create an API key at (platform.claude.com/redacted)
```

**Why It's Problematic:** `platform.claude.com/docs/en/get-started` is a documentation/getting-started page, not the API key creation UI. Users who click this link to get their API key may need to navigate further to find the actual key creation page. The equivalent Copilot setup uses a pre-filled direct link to the GitHub token creation form.

**Suggested Fix:** Replace with a direct link to the API console, e.g., `https://console.anthropic.com/settings/keys` (the actual key creation page). This aligns with the quality of the `COPILOT_GITHUB_TOKEN` instructions which link directly to the token creation form.

**Affected Files:** `docs/src/content/docs/reference/auth.mdx:103`

</details>

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

- **Issue 1: Web Search Guide Only Shows Copilot Engine** — File: `docs/src/content/docs/guides/web-search.md`. The guide's only code example uses `engine: copilot`. Claude and Codex users can use the exact same Tavily MCP setup (it's engine-agnostic), but there's no Claude example to confirm this. A Claude user reading this guide may wonder if web search works for their engine. [Day 3 - Persistent]

- **Issue 2: Gemini Missing from Quick Start and Add-Wizard Description** — File: `docs/src/content/docs/setup/quick-start.mdx`. Prerequisites list only Copilot, Claude, and Codex. Step 3 authentication section only mentions three secrets. Gemini (`GEMINI_API_KEY`) is a fully supported engine per `docs/src/content/docs/reference/engines.md` and `docs/src/content/docs/reference/auth.mdx` but is absent from the onboarding entry point. [Day 3 - Persistent]

- **Issue 3: engines.md Links to Potentially Outdated Claude URL** — File: `docs/src/content/docs/reference/engines.md` line 17. The table links Claude to `https://www.anthropic.com/index/claude` which is an older URL format. Compare: Copilot links to GitHub docs, Codex links to the OpenAI blog post. A consistent, current Anthropic URL (e.g., `https://www.anthropic.com/claude`) would be more reliable. [Day 3 - Persistent]

---

### Engine Comparison Analysis

#### Documentation Quality by Engine

| Engine | Setup Docs | Examples | Auth Docs | Overall |
|--------|-----------|----------|-----------|---------|
| Copilot | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ |
| Claude | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ |
| Codex | ⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ |
| Gemini | ⭐⭐⭐ | ⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ |
| Custom | ⭐⭐⭐ | ⭐⭐ | N/A | ⭐⭐⭐ |

**Notes:** Copilot's higher score reflects its position as the default engine and greater volume of examples. Claude is well-documented as a first-class alternative. Gemini scores lower due to absence from the Quick Start onboarding path.

---

### Tool Availability Analysis

#### Engine-Agnostic Tools (All Engines)
`edit`, `github`, `bash`, `web-fetch`, `playwright`, `cache-memory`, `repo-memory`, `agentic-workflows`, `qmd`, custom `mcp-servers`, `safe-outputs`

#### Engine-Specific Features
- `web-search` — Native in Codex; MCP-based for Copilot/Claude/Gemini (all work, different mechanism)
- `max-turns` — Claude only (iteration limit per run)
- `max-continuations` — Copilot only (multi-run autopilot)
- `engine.agent` — Copilot only (`.github/agents/` custom agent files)

All these are clearly documented in the Feature Comparison table at `docs/src/content/docs/reference/engines.md:27-36`.

---

### Authentication Requirements

#### Current Documentation Coverage

- ✅ Copilot: Detailed instructions with direct pre-filled PAT creation link
- ⚠️ Claude: Instructions present but setup URL directs to docs page rather than API key creation console
- ✅ Codex: Clear instructions with direct link to `platform.openai.com/api-keys`
- ✅ Gemini: Clear instructions with direct link to `aistudio.google.com/api-keys`

#### Secret Names

| Engine | Secret Name | Link Quality |
|--------|------------|-------------|
| Copilot | `COPILOT_GITHUB_TOKEN` | ⭐⭐⭐⭐⭐ (pre-filled form) |
| Claude | `ANTHROPIC_API_KEY` | ⭐⭐⭐ (docs page, not console) |
| Codex | `OPENAI_API_KEY` | ⭐⭐⭐⭐⭐ (direct API keys page) |
| Gemini | `GEMINI_API_KEY` | ⭐⭐⭐⭐⭐ (direct API keys page) |

---

### Example Workflow Analysis

#### Workflow Count by Engine

```
engine: copilot  — 87 workflows  (down 1 from yesterday)
engine: claude   — 35 workflows  (down 1 from yesterday)
engine: codex    — 18 workflows
engine: custom   —  1 workflow

The 1-workflow drop in both claude and copilot counts is likely due to normal codebase evolution (e.g., workflow restructuring or removal). It does not indicate a documentation regression.

Quality of Claude Examples

With 35 Claude workflows covering use cases including: daily reports, code analysis, security review, documentation maintenance, and observability — Claude users have ample real-world examples. Workflow categories using engine: claude include production workflows used in this very repository (e.g., claude-code-user-docs-review.md — the workflow generating this report).

---

Recommended Actions

Priority 1: Fix the Anthropic API Key Setup URL (Major Obstacle)

1. Update ANTHROPIC_API_KEY link — Replace (platform.claude.com/redacted) with the direct API console URL — File: docs/src/content/docs/reference/auth.mdx:103`

Priority 2: Add Gemini to Quick Start Onboarding

2. Add Gemini to prerequisites — "GitHub Copilot, Anthropic Claude, OpenAI Codex, or Google Gemini" — File: docs/src/content/docs/setup/quick-start.mdx
3. Add GEMINI_API_KEY to Step 3 — List all four secrets in the add-wizard step description — File: docs/src/content/docs/setup/quick-start.mdx

Priority 3: Nice-to-Have Enhancements

4. Add Claude/Codex example to web search guide — Change engine: copilot to engine: claude or add a second snippet — File: docs/src/content/docs/guides/web-search.md
5. Update Claude URL in engines.md — Replace anthropic.com/index/claude with a current URL — File: docs/src/content/docs/reference/engines.md:17

---

Positive Findings

What works well for Claude Code users:

• ✅ Quick Start is genuinely multi-engine — Claude is listed first among alternatives alongside Copilot
• ✅ Engine Feature Comparison table (engines.md) clearly shows what Claude supports vs. what's Copilot-only
• ✅ Authentication docs are thorough — auth.mdx covers all 4 engines with step-by-step instructions
• ✅ 35 Claude workflow examples — Substantial real-world Claude workflows in the repo
• ✅ No hidden Copilot requirements — Every documented feature either works with Claude or is clearly marked Copilot-only
• ✅ How It Works explicitly names Claude — Not buried in a footnote
• ✅ Version pinning documented for Claude — engine: { id: claude, version: "2.1.70" } example provided
• ✅ Custom endpoint support for Claude — ANTHROPIC_BASE_URL documented for proxy/enterprise setups

---

Conclusion

Can Claude Code Users Successfully Adopt gh-aw?

Answer: Yes, with minor friction

The documentation has matured to treat Claude as a genuine first-class engine. A developer who uses Claude Code exclusively can follow the Quick Start guide, select Claude as their engine, set ANTHROPIC_API_KEY, and have a working automated workflow within the documented ~10 minutes. The engine feature comparison table ensures no surprises about which Copilot-specific features they won't have access to.

The four persistent issues are genuine improvement opportunities but none prevent successful adoption. The most impactful fix (Priority 1) is a two-line change to a single file.

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: Stable at 8/10 for 3 consecutive days

No documentation regressions. No fixes applied to the persistent issues either. Recommend flagging these four issues for a documentation sprint before they accumulate further.

---

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/introduction/architecture.mdx
• docs/src/content/docs/reference/tools.md
• docs/src/content/docs/setup/cli.md
• docs/src/content/docs/reference/engines.md
• docs/src/content/docs/reference/auth.mdx
• docs/src/content/docs/guides/web-search.md

---

References:

• §23799204919 — this workflow run
• §23746552250 — yesterday's review run

AI generated by Claude Code User Documentation Review · history

• expires on Apr 1, 2026, 1:21 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 #23897.