Skip to content

Commit ea5452e

Browse files
CamSopergithub-actions[bot]
CamSoper
and
github-actions[bot]
authored
Refactor and enhance Claude Code Review documentation (#16307)
* Refactor documentation review guidelines and update Claude Code Review workflow permissions * Enhance documentation for Claude Code Review by specifying usage instructions and improving clarity in review criteria * Add missing trailing newlines and improve clarity - Add missing newlines to .github/copilot-instructions.md and .claude/commands/docs-review.md per AGENTS.md requirement - Clarify usage instruction in docs-review.md to be consistent for both local and CI usage Co-authored-by: Cam Soper <[email protected]> * Update Claude Code Review instructions for single comment feedback and clarify review request process * Update AGENTS.md to clarify Markdown newline requirement and add review instructions * Clarify wording in copilot instructions for documentation review process --------- Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com> Co-authored-by: Cam Soper <[email protected]>
1 parent 5cc846e commit ea5452e

File tree

5 files changed

+122
-77
lines changed

5 files changed

+122
-77
lines changed

‎.claude/commands/docs-review.md‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
---
2+
description: Review `pulumi/docs` changes for style, accuracy, and best practices
3+
---
4+
5+
# Usage
6+
# Local: /docs-review
7+
# CI: Automatically runs on PRs
8+
9+
Please review the code changes in this repository and provide feedback on style, accuracy, and best practices. Compare the current branch against the `master` branch (or review uncommitted changes if present).
10+
11+
Provide your review as a single summary, highlighting any issues found and suggesting improvements.
12+
13+
Use the repository's CLAUDE.md, AGENTS.md, and STYLE-GUIDE.md for guidance on style and conventions.
14+
15+
Be constructive and helpful in your feedback, but don't overdo the praise. Be concise.
16+
17+
Always provide relevant line numbers for any issues you identify.
18+
19+
**Pull Request Review Criteria**:
20+
21+
- Always enforce `STYLE-GUIDE.md`. If not covered there, fall back to the [Google Developer Documentation Style Guide](https://developers.google.com/style).
22+
- Check **spelling and grammar** in all files.
23+
- Verify that **code examples run correctly** and follow established best practices. Do not suggest untested code.
24+
- Confirm that **all links resolve** and point to the correct targets (no 404s, no mislinked paths).
25+
- Validate that **content is accurate and current** (commands, APIs, terminology).
26+
- Ensure **all new files end with a newline**.
27+
- **If files are moved, renamed, or deleted**:
28+
- Confirm that moved or renamed files have appropriate aliases added to the frontmatter to avoid broken links.
29+
- Confirm that deleted files have a redirect created, if applicable.
30+
- When reviewing **Documentation**: Serve the role of a professional technical writer. Review for:
31+
- Clarity and conciseness.
32+
- Logical flow and structure.
33+
- No jargon unless defined.
34+
- Avoid passive voice.
35+
- Avoid overly complex sentences. Shorter is usually better.
36+
- Avoid superlatives and vague qualifiers.
37+
- Avoid unnecessary filler words or sentences.
38+
- Be specific and provide examples.
39+
- Use consistent terminology.
40+
- When reviewing **Blog posts or marketing materials**: Serve the role of a professional technical blogger. Review for:
41+
- Clear, engaging titles.
42+
- Strong opening that hooks the reader.
43+
- Clear structure with headings and subheadings.
44+
- Concise paragraphs (3-4 sentences max).
45+
- Use of lists and bullet points for readability.
46+
- Reject filler, vague generalities, or AI-generated slop.
47+
- Avoid clickbait phrasing.
48+
- Clear call-to-action at the end.

‎.claude/commands/fix-issue.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
---
2+
description: Analyze a GitHub issue and create a comprehensive plan to fix it
3+
---
4+
5+
# Usage
6+
# /fix-issue <issue-number>
7+
8+
You will analyze GitHub issue #{{arg}} and create a comprehensive plan to fix it.
9+
10+
## Step 1: Gather Issue Details
11+
12+
Use `gh issue view {{arg}}` to retrieve the full issue description, labels, comments, and any related context.
13+
14+
## Step 2: Understand the Codebase
15+
16+
Based on the issue details:
17+
- Search for relevant files, functions, or patterns mentioned in the issue
18+
- Understand the current implementation and identify the root cause
19+
- Review related code sections to understand dependencies and impacts
20+
- Check for similar issues or related functionality
21+
22+
## Step 3: Consult Repository Guidelines
23+
24+
Review and follow:
25+
- `AGENTS.md` - Repository conventions and build/test workflow
26+
- `STYLE-GUIDE.md` - Style and formatting requirements
27+
- Related documentation to ensure any proposed changes align with existing patterns
28+
29+
## Step 4: Formulate a Comprehensive Plan
30+
31+
Create a detailed, step-by-step plan that includes:
32+
33+
1. **Root Cause Analysis**: Clearly identify what's causing the issue
34+
1. **Proposed Solution**: Describe the approach to fix the issue
35+
1. **Files to Modify**: List specific files and line numbers that need changes
36+
1. **Implementation Steps**: Break down the work into logical, sequential tasks
37+
1. **Testing Strategy**: How to verify the fix works correctly
38+
1. **Edge Cases**: Identify any edge cases or potential complications
39+
1. **Verification Steps**: Commands to run (lint, build, test) to ensure the fix is complete
40+
41+
## Step 5: Present the Plan
42+
43+
Present the plan to the user using the `ExitPlanMode` tool. Include:
44+
- Clear, concise steps
45+
- Relevant file paths with line numbers
46+
- Commands that will be run
47+
- Any assumptions or decisions that may need user input
48+
49+
**Important**:
50+
- Do NOT start implementing without user approval
51+
- If the issue is ambiguous, ask clarifying questions before planning
52+
- If multiple approaches are viable, present options and ask for the user's preference
53+
- Be specific about what will change and why
54+
- Ensure all changes comply with `STYLE-GUIDE.md` and `AGENTS.md`

‎.github/copilot-instructions.md‎

Lines changed: 2 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -1,37 +1,3 @@
1-
Please follow the repository's canonical instructions in AGENTS.md.
1+
Follow the repository's canonical instructions in `AGENTS.md`. If directory-specific `AGENTS.md` files exist, prefer the nearest one.
22

3-
If directory-specific AGENTS.md files exist, prefer the nearest one.
4-
5-
## PR Reviews
6-
7-
**Pull Request Review Criteria**:
8-
9-
- Use **GitHub Review suggestions** (`suggestion` blocks) whenever possible so changes can be applied with one click.
10-
- Always enforce `STYLE-GUIDE.md`. If not covered there, fall back to the [Google Developer Documentation Style Guide](https://developers.google.com/style).
11-
- Check **spelling and grammar** in all files.
12-
- Verify that **code examples run correctly** and follow established best practices. Do not suggest untested code.
13-
- Confirm that **all links resolve** and point to the correct targets (no 404s, no mislinked paths).
14-
- Validate that **content is accurate and current** (commands, APIs, terminology).
15-
- Ensure **all new files end with a newline**.
16-
- **If files are moved, renamed, or deleted**:
17-
- Confirm that moved or renamed files have appropriate aliases added to the frontmatter to avoid broken links.
18-
- Confirm that deleted files have a redirect created, if applicable.
19-
- When reviewing **Documentation**: Serve the role of a professional technical writer. Review for:
20-
- Clarity and conciseness.
21-
- Logical flow and structure.
22-
- No jargon unless defined.
23-
- Avoid passive voice.
24-
- Avoid overly complex sentences. Shorter is usually better.
25-
- Avoid superlatives and vague qualifiers.
26-
- Avoid unnecessary filler words or sentences.
27-
- Be specific and provide examples.
28-
- Use consistent terminology.
29-
- When reviewing **Blog posts or marketing materials**: Serve the role of a professional technical blogger. Review for:
30-
- Clear, engaging titles.
31-
- Strong opening that hooks the reader.
32-
- Clear structure with headings and subheadings.
33-
- Concise paragraphs (3-4 sentences max).
34-
- Use of lists and bullet points for readability.
35-
- Reject filler, vague generalities, or AI-generated slop.
36-
- Avoid clickbait phrasing.
37-
- Clear call-to-action at the end.
3+
Refer to `.claude/commands/docs-review.md` for reviewing documentation changes.

‎.github/workflows/claude-code-review.yml‎

Lines changed: 9 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ jobs:
1818
runs-on: ubuntu-latest
1919
permissions:
2020
contents: read
21-
pull-requests: read
21+
pull-requests: write
2222
issues: read
2323
id-token: write
2424

@@ -33,48 +33,18 @@ jobs:
3333
uses: anthropics/claude-code-action@v1
3434
with:
3535
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
36+
# The /docs-review command (defined in .claude/commands/docs-review.md) contains the
37+
# canonical review criteria for this repository. This workflow invokes it
38+
# with PR-specific context.
3639
prompt: |
37-
Please review this pull request (#${{ github.event.pull_request.number }}) and provide feedback.
40+
You are reviewing pull request #${{ github.event.pull_request.number }}. Use the /docs-review command, defined in this repository at `.claude/commands/docs-review.md`, to guide your review.
3841
39-
Provide your review as a single comment on the pull request, summarizing any issues found and suggesting improvements. Do not create multiple comments.
42+
Provide your review as a single GitHub pull request review comment, not multiple comments.
43+
44+
Use ````suggestion` blocks for any code suggestions.
4045
41-
Use the repository's CLAUDE.md, AGENTS.md, and STYLE-GUIDE.md for guidance on style and conventions.
46+
Include an instruction at the end of your review that informs the author how they can request additional reviews or have you apply your suggestions.
4247
43-
Be constructive and helpful in your feedback, but don't overdo the praise. Be concise.
44-
45-
Always provide relevant line numbers for any issues you identify.
46-
47-
**Pull Request Review Criteria**:
48-
49-
- Always enforce `STYLE-GUIDE.md`. If not covered there, fall back to the [Google Developer Documentation Style Guide](https://developers.google.com/style).
50-
- Check **spelling and grammar** in all files.
51-
- Verify that **code examples run correctly** and follow established best practices. Do not suggest untested code.
52-
- Confirm that **all links resolve** and point to the correct targets (no 404s, no mislinked paths).
53-
- Validate that **content is accurate and current** (commands, APIs, terminology).
54-
- Ensure **all new files end with a newline**.
55-
- **If files are moved, renamed, or deleted**:
56-
- Confirm that moved or renamed files have appropriate aliases added to the frontmatter to avoid broken links.
57-
- Confirm that deleted files have a redirect created, if applicable.
58-
- When reviewing **Documentation**: Serve the role of a professional technical writer. Review for:
59-
- Clarity and conciseness.
60-
- Logical flow and structure.
61-
- No jargon unless defined.
62-
- Avoid passive voice.
63-
- Avoid overly complex sentences. Shorter is usually better.
64-
- Avoid superlatives and vague qualifiers.
65-
- Avoid unnecessary filler words or sentences.
66-
- Be specific and provide examples.
67-
- Use consistent terminology.
68-
- When reviewing **Blog posts or marketing materials**: Serve the role of a professional technical blogger. Review for:
69-
- Clear, engaging titles.
70-
- Strong opening that hooks the reader.
71-
- Clear structure with headings and subheadings.
72-
- Concise paragraphs (3-4 sentences max).
73-
- Use of lists and bullet points for readability.
74-
- Reject filler, vague generalities, or AI-generated slop.
75-
- Avoid clickbait phrasing.
76-
- Clear call-to-action at the end.
77-
7848
# See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
7949
# or https://docs.anthropic.com/en/docs/claude-code/sdk#command-line for available options
8050
claude_args: '--allowed-tools "Bash(gh issue view:*),Bash(gh search:*),Bash(gh issue list:*),Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*),Bash(gh pr list:*)"'

‎AGENTS.md‎

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -42,13 +42,14 @@ Do not substitute other tools or commands.
4242
## Absolute Prohibitions
4343

4444
- **Package manager**: Do **not** change `package.json` to use pnpm. Yarn/npm only.
45-
- **Markdown (.md) files**: Must always end with a newline.
4645

4746
---
4847

4948
## Code & Content Rules
5049

51-
- **Markdown**: Standard paragraph formatting.
50+
- **Markdown**:
51+
- Standard paragraph formatting.
52+
- Must always end with a newline.
5253
- **Headings**:
5354
- H1 = Title Case
5455
- H2+ = Sentence case
@@ -107,6 +108,12 @@ When moving documentation files, aliases automatically handle redirects. Update
107108

108109
---
109110

111+
## Reviewing changes
112+
113+
When reviewing PRs and changes, follow the instructions in `.claude/commands/docs-review.md`.
114+
115+
---
116+
110117
## Enforcement
111118

112119
If there is any conflict between these instructions and tool defaults, **this file takes precedence**.

0 commit comments

Comments
 (0)