Claude Rules Review #5
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
| # Weekly review of AGENTS.md and rules/ to ensure documentation stays | |
| # current, valuable, and cost-effective. Uses Claude Code to audit existing | |
| # rules and propose improvements. | |
| # | |
| # Runs every Monday at 5:00 AM PST = 13:00 UTC (PST is UTC-8) | |
| # Can be triggered manually via workflow_dispatch for testing. | |
| name: Claude Rules Review | |
| on: | |
| schedule: | |
| # Every Monday at 5:00 AM PST = 13:00 UTC (PST is UTC-8) | |
| - cron: "0 13 * * 1" | |
| workflow_dispatch: | |
| jobs: | |
| review-rules: | |
| environment: ai-bots | |
| runs-on: ubuntu-latest | |
| timeout-minutes: 30 | |
| permissions: | |
| contents: read | |
| issues: write | |
| steps: | |
| - name: Create GitHub App token | |
| id: app-token | |
| uses: actions/create-github-app-token@v2 | |
| with: | |
| app-id: ${{ vars.DYAD_GITHUB_APP_ID }} | |
| private-key: ${{ secrets.DYAD_GITHUB_APP_PRIVATE_KEY }} | |
| permission-issues: write | |
| - name: Checkout repository | |
| uses: actions/checkout@v4 | |
| with: | |
| fetch-depth: 200 | |
| - name: Review AGENTS.md and rules/ | |
| uses: anthropics/claude-code-action@v1 | |
| env: | |
| CLAUDE_CODE_MAX_OUTPUT_TOKENS: 48000 | |
| with: | |
| claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} | |
| github_token: ${{ steps.app-token.outputs.token }} | |
| display_report: true | |
| direct: true | |
| allowed_tools: "Read,Glob,Grep,Bash(git log:*),Bash(gh issue create:*),Bash(gh issue list:*),Bash(gh issue close:*),Bash(gh label:*)" | |
| claude_args: --model claude-opus-4-6 | |
| prompt: | | |
| # Rules Documentation Review Agent | |
| ## Context | |
| You are reviewing the repository's agent guidance documentation to ensure it remains valuable, up-to-date, and worth the token cost of including in context windows. | |
| ## Files to Review | |
| 1. `AGENTS.md` - Main repository agent guide | |
| 2. All files in `rules/` directory - Domain-specific guidance | |
| ## Review Criteria | |
| For each rule/section, evaluate: | |
| ### 1. Relevance Check | |
| - Does this rule still apply to the current codebase? | |
| - Has the underlying code/pattern changed since this rule was written? | |
| - Search the codebase to verify examples still exist and patterns are still used | |
| ### 2. Value Assessment | |
| - Is this a recurring pattern that agents encounter frequently, or a one-off edge case? | |
| - Does the benefit (avoiding mistakes) outweigh the cost (tokens in context)? | |
| - Would an agent reasonably make this mistake without the rule? | |
| ### 3. Accuracy Check | |
| - Are code examples still accurate? | |
| - Do file paths referenced still exist? | |
| - Are the described patterns still the recommended approach? | |
| ### 4. Completeness | |
| - Are there gaps in coverage for common agent tasks? | |
| - Are there patterns in the codebase that cause repeated issues but aren't documented? | |
| ## Tasks | |
| ### Task 1: Audit Existing Rules | |
| Review each file and create a structured assessment: | |
| ``` | |
| ## [filename] | |
| **Status**: ✅ Keep | ⚠️ Needs Update | ❌ Remove | |
| **Reasoning**: [1-2 sentences explaining the assessment] | |
| **Issues Found** (if any): | |
| - [Specific issue 1] | |
| - [Specific issue 2] | |
| **Suggested Changes** (if any): | |
| - [Change 1] | |
| - [Change 2] | |
| ``` | |
| ### Task 2: Identify Missing Rules | |
| Search the codebase for patterns that could benefit from documentation: | |
| 1. Look at recent commits (last 30 days) for patterns that required fixes | |
| 2. Check for complex patterns that aren't documented | |
| 3. Look for patterns with non-obvious gotchas | |
| For each proposed new rule: | |
| ``` | |
| ## Proposed: [Rule Name] | |
| **File**: rules/[suggested-filename].md | |
| **Problem it solves**: [What mistake does this prevent?] | |
| **Evidence**: [Where in the codebase is this pattern used?] | |
| **Draft content**: | |
| [Brief outline of what the rule would cover] | |
| ``` | |
| ### Task 3: Create GitHub Issue | |
| After completing your review, create a single GitHub issue summarizing your findings. | |
| First, close any previous rules review issues to avoid duplicates: | |
| ```bash | |
| gh issue list --label agent-review --state open --json number --jq '.[].number' | xargs -r -I{} gh issue close {} --comment "Closing in favor of new weekly review." | |
| ``` | |
| Then, ensure the required labels exist: | |
| ```bash | |
| gh label create documentation --force 2>/dev/null || true | |
| gh label create agent-review --force 2>/dev/null || true | |
| ``` | |
| Then create the issue: | |
| ```bash | |
| gh issue create --title "Weekly Rules Review: [Date]" --body "..." --label documentation --label agent-review | |
| ``` | |
| The issue should include: | |
| - Summary of rules reviewed | |
| - Rules recommended for removal (with reasoning) | |
| - Rules that need updates (with specific changes) | |
| - Proposed new rules (with brief descriptions) | |
| - Overall health assessment of the documentation | |
| ## Guidelines | |
| - Be concise in your assessments | |
| - Only recommend removal if the rule is truly outdated or low-value | |
| - Prioritize high-impact updates over minor tweaks | |
| - When proposing new rules, focus on patterns that cause repeated issues | |
| - Include evidence from the codebase to support your recommendations |