chore: make claude-code-review workflow prompt generic#301
Merged
Conversation
Push project-specific review priorities out of the workflow YAML and into AGENTS.md / CLAUDE.md / specs/*.md — the documents that already describe the project. The workflow prompt now states only generic constraints (documented-invariant compliance, public-surface care, gitflow, test coverage) and tells the reviewer where to find the project-specific rules. Rationale: the anthropics/claude-code-action validates the workflow YAML byte-for-byte against the default branch before exchanging the OIDC token. Any project specifics baked into the workflow turn into a gate against ordinary work — every doc-shift in the codebase would require a workflow update, which can't ride along on the same PR. Pushing the specifics into AGENTS.md / specs/ removes that coupling: the docs evolve freely with code, the workflow stays stable. The bot now reads the current AGENTS.md and specs/ at review time, so this prompt remains accurate even as the project's conventions evolve.
Per review: keep the existing 'Focus on real issues, ordered by severity:' opening and the numbered 'Spec drift' / 'Downstream contract' / 'Test coverage' / 'Gitflow' priorities. The priorities ARE specific — they target real issue classes — and the project specifics they target live in AGENTS.md and specs/*.md, which the prompt now points the bot at without inlining their content. Removed every 'generic' qualifier. Each priority names the concrete issue class it cares about and references the doc that contains the project-specific definition (e.g. 'mock layers, cassette workflow, parametrised harness' live in specs/04-testing.md; the version-bump policy and gitflow rules live in AGENTS.md). The bot reads the current docs at review time, so no project specifics need to live in the workflow YAML.
admin-sbneto
approved these changes
May 25, 2026
sbneto
added a commit
that referenced
this pull request
May 25, 2026
…rompt PR #301 landed the generic claude-code-review workflow prompt on develop. Merging develop in so this PR's workflow file matches the default branch byte-for-byte and the bot review can run again.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
TL;DR
The
claude-code-reviewworkflow prompt currently has project-specific architecture rules baked into the YAML. Push them out intoAGENTS.md/CLAUDE.md/specs/*.md— the documents that already describe the project — and shrink the workflow to a generic review posture that points at those docs.Why
The
anthropics/claude-code-action@v1validates the workflow YAML byte-for-byte against the default branch before exchanging the OIDC token. Any project specifics inside the workflow turn into a gate against ordinary work:This bit polyswarm-api PR #298 twice. Once a stale
PolyswarmAPIBasereference in the prompt; once a stale set of "carve-out" review priorities that no longer match the unasync-codegen architecture.The fix: keep the workflow YAML stable. Project specifics live in
AGENTS.mdandspecs/*.md, which evolve naturally with the code.What changes
.github/workflows/claude-code-review.yml— prompt content. The workflow'son:trigger, permissions, action version, allowed-tools list, and OIDC plumbing are unchanged.Before: 5 numbered priorities with explicit references to
PolyswarmAPIBase,aio/__init__.py,ClientTestCase,polyswarm_api.aio.upload.*, VCR cassette workflow, develop/master gitflow.After: a short opening that points the reviewer at
AGENTS.md,CLAUDE.md, andspecs/*.mdas the source of truth, followed by generic review priorities (documented-invariant compliance, public-surface care, gitflow, test coverage) that name no specific file paths or class names.Verification
Workflow YAML validity:
prompt:block is rewritten.Behaviour after merge:
AGENTS.md+specs/, so any conventions documented there are picked up automatically.Out of scope
This PR doesn't change
AGENTS.mdor any spec — those documents already carry the project specifics the prompt used to duplicate. If a spec needs to be added or rewritten (e.g., a dedicated "Review priorities" section), do it in a separate PR.