Craft a company-level code review prompt (#471)

Craft a reusable, overridable, company-level code reviewing skill

Author: theMickster

.claude/README.md

@@ -8,11 +8,40 @@ This directory contains Claude Code configuration files for the gh-actions repos
 .claude/
 ├── CLAUDE.md              # General project context and guidelines
 ├── commands/              # Custom slash commands
-│   └── review-pr.md      # /review-pr command for PR reviews
+│   └── review-pr.md
 └── prompts/               # Workflow-specific prompts
-    └── review-code.md    # Used by review-code.yml workflow
+    └── bitwarden-review-code.md
+    └── review-code.md
 ```
 
+## Automated Workflow Reviews
+
+The `review-code.yml` workflow uses TWO prompt files:
+
+1. **Bitwarden company-wide prompt** (`.claude/prompts/bitwarden-review-code.md`)
+   - Stored in `bitwarden/gh-actions` repository
+   - Contains common review criteria for all Bitwarden repos
+   - Automatically fetched during workflow execution
+
+2. **Repository-specific gate** (`.claude/prompts/review-code.md`)
+   - Must exist in each repo that wants Claude reviews
+   - Contains repo-specific review instructions
+   - Acts as an "opt-in" gate for the review process
+
+**How it works:**
+
+1. Workflow triggers on a PR
+2. PR is validated as viable for a Claude Code review
+3. Workflow pulls the `.claude/prompts/bitwarden-review-code.md` file from the `gh-actions` repo.
+4. Workflow pulls the `.claude/prompts/review-code.md` file from the caller's repo (e.g. `server`, `clients`, `sdk-internal`, etc.)
+5. Workflow combines information from Steps 3 and 4 to create a Claude Code Action PR review prompt
+6. Claude executes the GitHub Action and appends feedback in the form of a summary comment with findings and inline comments (if necessary).
+
+**To enable in our repos:**
+
+1. Create `.claude/prompts/review-code.md` with review criteria
+2. Workflow runs automatically on subsequent pull requests
+
 ## Custom Commands
 
 ### `/review-pr` - Pull Request Review
@@ -39,22 +68,6 @@ Triggers a comprehensive PR code review in your current Claude Code session.
 @claude /review-pr
 ```
 
-## Automated Workflow Reviews
-
-The `review-code.yml` workflow uses the `.claude/prompts/review-code.md` to automatically review PRs via GitHub Actions in each Bitwarden repo. The `review-code.md` is used as a gate to execute the `review-code.yml` workflow. Repos without this file will not see Claude code reviews performed on each pull request.
-
-**How it works:**
-
-1. Workflow triggers on non-draft PRs
-2. Reads `.claude/prompts/review-code.md` from the PR's branch
-3. Posts review as a sticky comment
-4. Updates comment on new commits
-
-**To enable in our repos:**
-
-1. Create `.claude/prompts/review-code.md` with review criteria
-2. Workflow runs automatically on subsequent pull requests
-
 ## Best Practices
 
 - **Commands** (`.claude/commands/`): For interactive Claude Code sessions

.claude/prompts/bitwarden-review-code.md

@@ -0,0 +1,62 @@
+# Bitwarden Code Review Prompt
+
+## Purpose
+
+Enforce Bitwarden company code review rules to produce concise, consistent, and excellent PR review comments from Claude Code. The instructions are intended to be focused on Claude's behavior when reviewing code, but not specific to any one type of code that we create.
+
+## Rules that **must** be followed
+
+1. **NEVER** use the text label "Issue". **ONLY** list items using the word **Finding**.
+   - Never emit a bare "#" followed immediately by digits (e.g., "#123"); write "Finding 123" instead.
+   - **Findings** only as a numbered list.
+   - **Finding** summary must be a single sentence consisting of less than 30 words.
+
+2. **ALWAYS** consider brevity in the PR summary comment. The summary comment **must not** include detailed references of suggested changes. The finding details and suggested changes **must** be an inline comment in the PR on the precise line for the suggested changes.
+
+3. **ALWAYS** use the Bitwarden Claude Code reviewer guidelines. The type of finding must align with one of our suggested emojis.
+   - ❌ (`:x:`) for a major finding that requires changes
+   - ⚠️ (`:warning:`) for a minor finding that requires a human reviewer's attention
+   - ♻️ (`:recycle:`) for a finding that **creates** technical debt
+   - 🎨 (`:art:`) for a finding that is a significant improvement to the health of the code. **DO NOT** nitpick.
+   - 💭 (`:thought_balloon:`) for a finding that is open inquiry
+
+4. **ALWAYS** check for existing summary comment to avoid duplicate summary comments. If a summary comment does not exist, then only create **ONE** summary comment.
+
+5. **ALWAYS** read the prior summary comment **before** starting on a code review.
+
+6. **ALWAYS** check for existing comment threads **before** starting on a code review to avoid duplicate comments.
+
+7. **NEVER** duplicate a comment thread.
+
+8. **ALWAYS** carefully read all resolved comment threads. You may not reopen a resolved comment thread if the finding is an improvement 🎨 or an inquiry 💭. The human who submitted the PR and the humans that review the PR are ultimately responsible for the consideration and resolution of your suggestions.
+
+9. **NEVER** list the files changed in a pull request in the summary comment. Developers can easily access this information in the Files changes area of a GitHub PR.
+
+10. **ALWAYS** Analyze the changeset systematically:
+
+  <thinking>
+  - What files were modified? (code vs config vs docs)
+  - What is the PR title? Does it clearly convey the intent of the code change?
+  - What is the PR description? Does it expand upon the PR title to convey important details?
+  - Is there new functionality or just modifications?
+  - What's the risk level of these changes?
+</thinking>
+
+11. **ALWAYS** use structured thinking throughout your review process. Plan your analysis in `<thinking>` tags before providing final feedback.
+
+12. **NEVER** write multiple long paragraphs. If context is required, then you **must** use a fenced code block. You **must** use collapsible <details> sections for lengthy explanations.
+
+- Brevity respects developer time leading to short feedback loops
+- Brevity saves tokens, processing time, and money
+- Brevity reduces noise in PR conversations and focuses attention on findings that **require** human discussion
+
+13. **NEVER do this for clean PRs:**
+
+- ❌ Multiple sections (Key Strengths, Changes, Code Quality, etc.)
+- ❌ Listing everything that was done correctly
+- ❌ Checkmarks for each file or pattern followed
+- ❌ Elaborate praise or detailed positive analysis
+
+14. **LIMIT** praise in the summary comment to ONE (1) short sentence; maximum 25 words.
+
+15. **ALWAYS** be respectful and professional in your PR comments. You are reviewing the code and not the developer creating the code. Think twice about the tone used in PR comments.

.claude/prompts/review-code.md

@@ -1,25 +1,17 @@
-Please review this pull request with a focus on:
+# GitHub Actions Repository Review Standards
 
-- Code quality and best practices
-- Potential bugs or issues
-- Security implications
-- Performance considerations
+You are reviewing code in the `gh-actions` repository from the perspective of an Expert DevOps Engineer with deep expertise in GitHub Actions, reusable workflows, and CI/CD best practices.
 
-Note: The PR branch is already checked out in the current working directory.
+## Critical Review Focus Areas
 
-Provide a comprehensive review including:
+**Workflow Linter Compliance**: All workflow files must comply with Bitwarden Workflow Linter rules. Verify external actions are pinned to commit hashes with version comments, permissions are explicitly set, job runners are version-pinned, and only approved actions are used.
 
-- Summary of changes since last review
-- Critical issues found (be thorough)
-- Suggested improvements (be thorough)
-- Good practices observed (be concise - list only the most notable items without elaboration)
-- Action items for the author
-- Leverage collapsible <details> sections where appropriate for lengthy explanations or code snippets to enhance human readability
+**Security-First**: Secrets must never appear in workflow logs or outputs. Verify proper use of `core.setSecret()` in TypeScript actions and correct Azure Key Vault integration patterns. Any code that could leak credentials is a critical finding requiring immediate correction.
 
-When reviewing subsequent commits:
+**Conciseness**: Workflows must be purposeful and concise. Reject unnecessary verbosity, redundant steps, or excessive logging. Every line must justify its existence.
 
-- Track status of previously identified issues (fixed/unfixed/reopened)
-- Identify NEW problems introduced since last review
-- Note if fixes introduced new issues
+**Reusability**: Favor reusable workflows and composite actions over code duplication. Identify opportunities to extract common patterns into reusable components that benefit the entire Bitwarden organization.
 
-IMPORTANT: Be comprehensive about issues and improvements. For good practices, be brief - just note what was done well without explaining why or praising excessively.
+**Documentation Quality**: Markdown files must be grammatically correct, properly formatted with consistent styling, and follow established patterns. README files must clearly document action inputs, outputs, and provide practical usage examples.
+
+**Code Formatting**: All code must pass Prettier formatting validation. Formatting violations indicate the pre-commit hook was bypassed and must be corrected.

.github/CODEOWNERS

@@ -19,3 +19,10 @@
 **/*.dockerignore @bitwarden/team-appsec @bitwarden/dept-bre
 **/entrypoint.sh @bitwarden/team-appsec @bitwarden/dept-bre
 **/docker-compose.yml @bitwarden/team-appsec @bitwarden/dept-bre
+
+# Claude related files
+.claude/ @bitwarden/team-ai-sme
+.github/workflows/_respond.yml @bitwarden/team-ai-sme
+.github/workflows/_review-code.yml @bitwarden/team-ai-sme
+.github/workflows/respond.yml @bitwarden/team-ai-sme
+.github/workflows/review-code.yml @bitwarden/team-ai-sme

.github/workflows/_review-code.yml

@@ -123,17 +123,37 @@ jobs:
       - name: Build review prompt
         id: build-prompt
         env:
+          GH_TOKEN: ${{ github.token }}
           PR_REPO: ${{ github.repository }}
           PR_NUMBER: ${{ github.event.pull_request.number }}
           PR_TITLE: ${{ github.event.pull_request.title }}
           PR_BODY: ${{ github.event.pull_request.body }}
           PR_AUTHOR: ${{ github.event.pull_request.user.login }}
           PR_COMMIT: ${{ github.event.pull_request.head.sha }}
+          PROMPT_FILE: ".claude/prompts/review-code.md"
+          REUSABLE_PROMPT_REPO: "bitwarden/gh-actions"
+          REUSABLE_PROMPT_FILE: ".claude/prompts/bitwarden-review-code.md"
+          REUSABLE_PROMPT_TEMP_FILE: "/tmp/bitwarden-review-code-prompt.md"
         run: |
-          PROMPT_FILE=".claude/prompts/review-code.md"
+          set -e
+          echo "📥 Fetching Bitwarden prompt file..."
+
+          # Fetch the prompt file from gh-actions repo using GitHub API
+          gh api "repos/$REUSABLE_PROMPT_REPO/contents/$REUSABLE_PROMPT_FILE" \
+            --jq '.content' | base64 -d > "$REUSABLE_PROMPT_TEMP_FILE" || true
+
+          if [ -f "$REUSABLE_PROMPT_TEMP_FILE" ] && [ -s "$REUSABLE_PROMPT_TEMP_FILE" ]; then
+            echo "✅ Successfully fetched Bitwarden prompt file"
+            echo "📄 File size: $(wc -c < "$REUSABLE_PROMPT_TEMP_FILE") bytes"
+          else
+            echo "⚠️  Warning: Failed to fetch Bitwarden prompt file - continuing without it"
+            touch "$REUSABLE_PROMPT_TEMP_FILE"
+          fi
 
-          # Build the full prompt with GitHub context + repo's prompt
+          # Build the code review prompt
           {
+            cat "$REUSABLE_PROMPT_TEMP_FILE"
+            printf "\n\n---\n\n"
             printf "REPO: %s\n" "$PR_REPO"
             printf "PR NUMBER: %s\n" "$PR_NUMBER"
             printf "TITLE: %s\n" "$PR_TITLE"

.gitignore

@@ -29,3 +29,9 @@ npm-debug.log
 
 # Generated solution files
 gh-actions.sln
+
+# Claude Code local settings
+.claude/settings.local.json
+
+# Temporary workflow artifacts
+.gh-actions-temp/