Skip to content

Conversation

Copy link
Contributor

Copilot AI commented Aug 10, 2025

This PR significantly reduces the size and complexity of AGENTS.md to make it more efficient for AI assistants like GitHub Copilot, Claude Code, and similar tools to process and understand, while adding important setup guidance.

Problem

The original AGENTS.md file was 349 lines long with extensive verbose explanations, detailed examples for every crate, and decorative formatting that consumed excessive tokens when processed by AI assistants. This led to:

  • High token usage for AI context windows
  • Redundant information that AI can infer from context
  • Verbose examples that don't add value for code assistance
  • Missing guidance on pre-installed tools and development workflow

Solution

Streamlined the file to focus on essential, actionable information while removing unnecessary verbosity and adding critical setup notes:

Key Changes:

  • Removed verbose examples section (130+ lines) - replaced with concise key examples only
  • Eliminated decorative emojis and excessive formatting that add no functional value
  • Consolidated redundant information across sections
  • Simplified command references to essential development commands only
  • Added setup notes about pre-installed tools to prevent redundant installations
  • Updated Rust MSRV to 1.87.0
  • Added workflow guidance for final validation steps

What's Preserved and Enhanced:

  • Project structure and core crates overview
  • Essential development commands (just ready, just fmt, etc.)
  • Code navigation guidance for key locations
  • Common development task workflows
  • Performance and compatibility notes
  • New: Setup notes about pre-installed tools (cargo-insta, typos-cli, cargo-shear, dprint)
  • New: Guidance to run just ready as final step after commits
  • New: Notes about pre-installed Rust components (clippy, rust-docs, rustfmt)

Results

  • 70% size reduction: From 349 lines to 109 lines
  • Dramatically reduced token consumption for AI assistants
  • Enhanced utility with critical setup and workflow guidance
  • Verified functionality - all referenced commands and examples still work
  • Prevents tool installation errors by documenting pre-installed components

The concise version provides better guidance for AI assistants while being much more efficient to process, leading to improved performance, reduced costs, and fewer setup errors for AI-powered development tools.


💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.

@graphite-app
Copy link
Contributor

graphite-app bot commented Aug 10, 2025

How to use the Graphite Merge Queue

Add either label to this PR to merge it via the merge queue:

  • 0-merge - adds this PR to the back of the merge queue
  • hotfix - for urgent hot fixes, skip the queue and merge this PR next

You must have a Graphite account in order to use the merge queue. Sign up using this link.

An organization admin has enabled the Graphite Merge Queue in this repository.

Please do not merge from GitHub as this will restart CI on PRs being processed by the merge queue.

Co-authored-by: Boshen <1430279+Boshen@users.noreply.github.com>
Copilot AI changed the title [WIP] Make AGENTS.md consise for AI such as Github Copilot or Claude Code to read, consider less token usage. Make AGENTS.md concise for AI assistants - reduce token usage by 70% Aug 10, 2025
Copilot finished work on behalf of Boshen August 10, 2025 15:45
Copilot AI requested a review from Boshen August 10, 2025 15:45
@Boshen
Copy link
Member

Boshen commented Aug 10, 2025

@copilot keep the following:

  • just init has already been run, all tools (cargo-insta, typos-cli, cargo-shear, dprint) are already installed, do not run just init.
  • Rust and cargo components clippy, rust-docs and rustfmt has already been installed, do not install them.
  • Always run just ready as the last step after code has been committed to the repository.

Also change Rust MSRV to 1.87.0

Co-authored-by: Boshen <1430279+Boshen@users.noreply.github.com>
Copy link
Contributor Author

Copilot AI commented Aug 10, 2025

@copilot keep the following:

  • just init has already been run, all tools (cargo-insta, typos-cli, cargo-shear, dprint) are already installed, do not run just init.
    ...

Added the requested setup notes and updated MSRV to 1.87.0. The AGENTS.md now includes:

  • Note that just init and tools are already installed
  • Note that Rust components are already installed
  • Guidance to run just ready as final step after commits
  • Updated MSRV to 1.87.0

Commit: 8660f09

Copilot AI changed the title Make AGENTS.md concise for AI assistants - reduce token usage by 70% Make AGENTS.md concise for AI assistants with setup notes - reduce token usage by 70% Aug 10, 2025
Copilot finished work on behalf of Boshen August 10, 2025 15:59
@Boshen Boshen changed the title Make AGENTS.md concise for AI assistants with setup notes - reduce token usage by 70% docs(AGENTS.md): Make AGENTS.md concise for AI assistants with setup notes - reduce token usage by 70% Aug 10, 2025
@Boshen Boshen marked this pull request as ready for review August 10, 2025 16:10
Copilot AI review requested due to automatic review settings August 10, 2025 16:10
@github-actions github-actions bot added the C-docs Category - Documentation. Related to user-facing or internal documentation label Aug 10, 2025
Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull Request Overview

This PR streamlines the AGENTS.md file to optimize token usage for AI assistants by reducing verbosity and redundancy while adding essential setup guidance. The file is condensed from 349 lines to 109 lines (70% reduction) to improve efficiency for AI context windows.

Key Changes:

  • Removed verbose examples section (130+ lines) and replaced with concise key examples
  • Eliminated decorative formatting and redundant information
  • Added critical setup notes about pre-installed tools to prevent installation errors

@Boshen Boshen merged commit 9b5af3e into main Aug 10, 2025
5 checks passed
@Boshen Boshen deleted the copilot/fix-ee343377-d9e8-4f59-9cca-85a5ef76c5cb branch August 10, 2025 16:11
taearls pushed a commit to taearls/oxc that referenced this pull request Aug 12, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

C-docs Category - Documentation. Related to user-facing or internal documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants