feat: automate CLAUDE.md generation from RFC discussions #2199

Copilot · 2025-11-11T11:03:45Z

Implements GitHub Actions automation to generate CLAUDE.md from RFC discussions labeled RFC:Landed, providing AI coding assistants with project-specific contribution guidelines.

Changes

Script: `script/generate-claude-md.ts`

TypeScript implementation using Node.js --experimental-strip-types for direct execution
Fetches discussions from "Contribution RFC" category via gh cli GraphQL API
Extracts ## AI Instructions sections from RFC:Landed discussions
Generates individual RFC files in .contribution-guidelines/ with lowercase-dashed naming
Builds root CLAUDE.md with @.contribution-guidelines/[filename].md links
Removes obsolete files when labels are removed
Type-safe with proper interfaces for API responses

Workflow: `.github/workflows/generate-claude-md.yml`

Triggers: discussion labeled, unlabeled, edited events
Filters: "Contribution RFC" category using github.event.discussion.category.name from event context
Uses git CLI (git commit, git push) for commits instead of GitHub API
Creates PR to automated/claude-md-update branch (no direct commits)
Single streamlined job with Node.js 22.14.0 setup

Documentation

.contribution-guidelines/README.md: System overview and usage
CONTRIBUTING.md: Added AI Coding Guidelines section

Example Output

When an RFC titled "Testing Strategy" gets the RFC:Landed label:

Generated .contribution-guidelines/testing-strategy.md:

# Testing Strategy

[Content from ## AI Instructions section]

Generated CLAUDE.md:

# Contribution Guidelines

## Testing Strategy

@.contribution-guidelines/testing-strategy.md

Usage

Create discussion in "Contribution RFC" category
Add ## AI Instructions section with guidance for AI tools
Apply RFC:Landed label
Workflow creates PR with generated files for review

Fixes generate CLAUDE.md file from contibution guidelines #2198

Original prompt

This section details on the original issue you should resolve

<issue_title>generate CLAUDE.md file from contibution guidelines</issue_title>
<issue_description>## Why

CLAUDE.md is a file which gives context to different coding agents like copilot, cursor and some others. This file helps them to understand the project better and create PRs/generate code of better quality.

What

Generate CLAUDE.md from https://github.com/akash-network/console/discussions/categories/contribution-rfc?discussions_q=is%3Aopen+category%3A%22Contribution+RFC%22 using GHA.

For every discussion, we will use a separate file and will link it into root CLAUDE.md with a reference to that file. All sub-files will live in .contribution-guidelines folder. Every file has the same title as RFC discussion (lowercased with spaces replaced by dashes).

Implementation Details

AI Instructions Section in RFCs

Each RFC discussion must include a dedicated section called ## AI Instructions. The author of the RFC needs to add this section before changing the label to RFC:Landed. This section will contain instructions that will be extracted and included in the CLAUDE.md file.

Note: Currently, RFCs don't have this section. It needs to be added manually to existing RFC:Landed discussions.

GitHub Actions Automation

The automation script should be implemented in bash using gh cli and will:

Trigger on these discussion events:

labeled - when RFC:Landed label is added, create new file

unlabeled - when RFC:Landed label is removed, delete the file

edited - when discussion is edited, recreate (update) the file

Process:

Regenerate the entire CLAUDE.md structure on every event

Only update files that were actually modified

Create a PR with the changes for review (don't commit directly)

Root CLAUDE.md Structure

The root CLAUDE.md file should have the following structure:
## <RFC title>

@.contribution-guidelines/rfc-title.md  # lowercased, dashed
File Naming Convention

RFC discussion titles should be converted to filenames using this rule:

Convert to lowercase

Replace spaces with hyphens

Remove special characters

Example: "Testing Strategy" → testing-strategy.md

Workflow

GHA monitors discussions in the "Contribution RFC" category

When a discussion receives/loses the RFC:Landed label or is edited, the workflow triggers

Script extracts the ## AI Instructions section from all RFC:Landed discussions

Generates/updates files in .contribution-guidelines/ directory

Generates root CLAUDE.md with links to all sub-files

Creates a PR with changes for human review</issue_description>

<agent_instructions>follow repository rules from .cursor/rules folder and patterns from .github/workflows</agent_instructions>

Comments on the Issue (you are @copilot in this section)
@stalniy @coderabbitai did I miss something, is the task clear? if not, please update the description @stalniy 1. Let's call this section "## AI Instructions". Currently RFCs doesn't have this section, we need to add it manually, people will do this. 2. We can completely regenerate Claude.md file on every `labeled`, `unlabeled`, `edited` events on discussions of that specific category. The script can be implemented in bash with help of `gh cli`. We also need to update corresponding files but only if they were modified. When discussion receives required label then new file added, when discussion looses that label - file is removed. When discussion is edited file is recreated (basically updated) 3. Root CLAUDE.md will have a structure like this:
## <RFC title>

@.contribution-guidelines/rfc-title.md  # lowercased, dashed
Automated gha must create a PR which then will be reviewed by people </comment_new>
<comment_new>@stalniy
@coderabbitai, please update the issue description with details I've added in #2198 (comment)</comment_new>

Fixes generate CLAUDE.md file from contibution guidelines #2198

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

coderabbitai · 2025-11-11T11:03:58Z

Important

Review skipped

Bot user detected.

To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Note

Other AI code review bot(s) detected

CodeRabbit has detected other AI code review bot(s) in this pull request and will avoid duplicating their findings in the review comments. This may lead to a less comprehensive review.

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

Co-authored-by: stalniy <[email protected]>

stalniy · 2025-11-11T11:18:55Z

.github/workflows/generate-claude-md.yml

+
+      - name: Commit Changes
+        if: steps.check-changes.outputs.has_changes == 'true'
+        run: |


issue(blocking): can you commit using git cli tool, this will be much simpler

@copilot fix this

Done in 4a9b7e9. Simplified the workflow to use git CLI for commits with git commit and git push instead of the GitHub API.

stalniy · 2025-11-11T11:21:08Z

.github/workflows/generate-claude-md.yml

+          CATEGORY=$(gh api graphql -f query='
+            query($owner: String!, $repo: String!, $number: Int!) {
+              repository(owner: $owner, name: $repo) {
+                discussion(number: $number) {
+                  category {
+                    name
+                  }
+                }
+              }
+            }' -F owner="${GITHUB_REPOSITORY%/*}" -F repo="${GITHUB_REPOSITORY#*/}" -F number="$DISCUSSION_NUMBER" --jq '.data.repository.discussion.category.name')


question(blocking): don't you have category in github.event.discussion context variable?

@copilot fix this

Fixed in 4a9b7e9. Now using github.event.discussion.category.name directly in the job condition instead of making a separate API call.

stalniy · 2025-11-11T11:21:37Z

.github/workflows/generate-claude-md.yml

+      - name: Checkout Repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0


issue(blocking): no need to fetch everything

@copilot fix this

Fixed in 4a9b7e9. Removed fetch-depth: 0 from checkout action since we only need the latest commit.

stalniy · 2025-11-11T11:24:06Z

script/generate-claude-md.sh

issue(blocking): this script is overcomplicate, it's probably better to write it in ts and use node --experimental-strip-types flag to run it

@copilot fix this

Done in 4a9b7e9. Rewrote the script in TypeScript and now using node --experimental-strip-types to run it, which is much cleaner and type-safe.

- Replace bash script with TypeScript version using --experimental-strip-types - Use git CLI for commits instead of GitHub API - Use github.event.discussion.category.name directly instead of fetching - Remove fetch-depth: 0 as it's not needed - Simplify workflow with single job Co-authored-by: stalniy <[email protected]>

Initial plan

a278b61

Copilot AI assigned Copilot and stalniy Nov 11, 2025

Copilot started work on behalf of stalniy November 11, 2025 11:04 View session

Copilot AI and others added 3 commits November 11, 2025 11:09

feat: add CLAUDE.md generation workflow and script

71e13cd

Co-authored-by: stalniy <[email protected]>

docs: add README for contribution-guidelines directory

b1e7e69

Co-authored-by: stalniy <[email protected]>

docs: add AI guidelines section to CONTRIBUTING.md

bc1e4f6

Co-authored-by: stalniy <[email protected]>

Copilot AI changed the title ~~[WIP] Generate CLAUDE.md file from contribution guidelines~~ feat: automate CLAUDE.md generation from RFC discussions Nov 11, 2025

Copilot AI requested a review from stalniy November 11, 2025 11:18

Copilot finished work on behalf of stalniy November 11, 2025 11:18

stalniy requested changes Nov 11, 2025

View reviewed changes

Copilot started work on behalf of stalniy November 11, 2025 12:16 View session

Copilot AI requested a review from stalniy November 11, 2025 12:25

Copilot finished work on behalf of stalniy November 11, 2025 12:25

Copilot started work on behalf of stalniy November 11, 2025 12:26 View session

Copilot finished work on behalf of stalniy November 11, 2025 12:28

feat: automate CLAUDE.md generation from RFC discussions #2199

Are you sure you want to change the base?

feat: automate CLAUDE.md generation from RFC discussions #2199

Conversation

Copilot AI commented Nov 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Script: script/generate-claude-md.ts

Workflow: .github/workflows/generate-claude-md.yml

Documentation

Example Output

Usage

What

Implementation Details

AI Instructions Section in RFCs

GitHub Actions Automation

Root CLAUDE.md Structure

File Naming Convention

Workflow

Comments on the Issue (you are @copilot in this section)

Uh oh!

coderabbitai bot commented Nov 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review skipped

Other AI code review bot(s) detected

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 11, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 11, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 11, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 11, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Copilot AI commented Nov 11, 2025 •

edited

Loading

Script: `script/generate-claude-md.ts`

Workflow: `.github/workflows/generate-claude-md.yml`

coderabbitai bot commented Nov 11, 2025 •

edited

Loading