[WIP] Documentation Improvement for GitHub Copilot and AI Agents #114
Conversation
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
joe10832
approved these changes
Oct 2, 2025
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
Coding agent has begun work on Documentation Improvement for GitHub Copilot and AI Agents and will replace this description as work progresses.
See problem context
The following is a snapshot of a chat conversation between a user and an AI coding assistant. Prioritize later messages in the conversation.
User: - echo "E2E_TEST_SEED_PHRASE=your-test-seed-phrase-here" > .env
Edit .env to add your E2E_TEST_SEED_PHRASE and any other secrets
INFO: notify_waitpid_callback_by_pid: Child process 9573 has exited; no callback was registered
Documentation Issue Type
Location
Where is the documentation issue located?
/exampledirectory/docsdirectory.github/copilot-instructions.md).github/instructions/**/*.instructions.md)**/AGENTS.md)/CLAUDE.md)/GEMINI.md)AGENTS.md Enhanced with quick setup checklist, workflow examples, and agent-specific best practices
CLAUDE.md Added Claude-optimized setup workflow with analytical implementation examples
GEMINI.md Added rapid setup steps and performance-focused optimization examples
README.md Integrated new AI agent documentation section with clear navigation and quick start guideClaude AI Instructions for Onchain Test Kit
This document provides specific instructions for Claude when working on the Onchain Test Kit project. For general project context, also refer to AGENTS.md and .github/copilot-instructions.md.
Quick Setup for Claude
Initial Configuration Steps
Load project context: Familiarize yourself with the repository structure and existing patterns
Review dependencies: Understand the TypeScript, Playwright, and Viem ecosystem
Study wallet patterns: Examine existing wallet implementations for consistency
Test setup: Verify you can run the build and test pipeline
Claude's Optimal Usage Workflow
// 1. Analyze requirements thoroughly
// Example: Adding a new wallet action for token swaps
// 2. Research existing patterns
// Check how similar actions are implemented across wallets
// Review test patterns for comprehensive coverage
// 3. Plan implementation
interface SwapActionOptions {
shouldApprove: boolean;
tokenIn: string;
tokenOut: string;
amount: string;
slippage?: string;
}
// 4. Implement with error handling
async handleSwapAction(options: SwapActionOptions): Promise {
try {
const popup = await this.waitForPopup();
// Handle swap-specific UI interactions
await popup.getByTestId('swap-confirm').click();
} catch (error) {
throw new WalletActionError('Swap action failed', error);
}
}
// 5. Add comprehensive tests
test('token swap approval flow', async ({ page, metamask }) => {
// Test happy path
// Test rejection path
// Test error conditions
// Test with different token pairs
});
Claude-Specific Strengths and Focus Areas
Leverage Claude's Capabilities
Code reasoning: Use detailed analysis for complex blockchain testing scenarios
Pattern recognition: Identify and maintain consistent architectural patterns
Comprehensive explanations: Provide thorough documentation for complex wallet interactions
Edge case consideration: Think through various blockchain and wallet edge cases
Preferred Development Approach
When approaching tasks:
Analyze the full context of blockchain testing requirements
Consider wallet-specific behaviors and limitations
Think through async patterns and timing issues
Plan for cross-browser compatibility
2. Detailed Implementation Planning
Before making changes:
Review existing wallet implementations for patterns
Consider impact on all supported wallets (MetaMask, Coinbase, Phantom)
Plan for both unit tests and integration tests
Think through fork mode implications
3. Comprehensive Error Handling
Anticipate wallet connection timeouts
Handle network switching failures gracefully
Provide clear error messages for debugging
Consider retry mechanisms for flaky operations
Key Areas of Focus
Blockchain Testing Complexity
Fork mode testing: Understanding of mainnet forking for realistic testing
Multi-wallet scenarios: Handling different wallet behaviors consistently
Network switching: Chain-specific configurations and transitions
Transaction handling: Gas estimation, approval flows, and error states
TypeScript Excellence
Maintain strict typing throughout the codebase
Use proper generic constraints for wallet actions
Implement discriminated unions for action types
Ensure proper async/await typing with Playwright
Testing Architecture
// Preferred pattern for Claude to follow
const test = createOnchainTest(
configure()
.withMetaMask()
.withLocalNode({
fork: 'https://mainnet.base.org',
forkBlockNumber: specificBlockNumber, // Always use specific blocks
accounts: 5, // Reasonable number for testing
})
.withNetwork(baseMainnet) // Use viem chain configs
.build()
);
test('descriptive test name explaining the scenario', async ({ page, metamask, node }) => {
// Clear setup phase
await page.goto('http://localhost:3000');
// Explicit wallet interactions
await page.getByTestId('connect-button').click();
await metamask.handleAction('connect', { shouldApprove: true });
// Verify expected outcomes
await expect(page.getByTestId('wallet-address')).toBeVisible();
});
Configuration Builder Patterns
When extending the configuration builder:
Use method chaining consistently
Validate parameters at build time
Provide helpful error messages
Maintain backward compatibility
Common Scenarios for Claude
When debugging wallet problems:
Check extension preparation scripts first
Verify browser context configuration
Review timing issues in wallet popups
Consider wallet-specific quirks and behaviors
2. Fork Mode Configuration
For mainnet forking scenarios:
Always specify exact block numbers for reproducibility
Use appropriate RPC providers with sufficient rate limits
Consider the cost implications of fork testing
Plan for realistic token balances and contract states
3. Multi-Chain Testing
When working with multiple networks:
Use viem chain configurations consistently
Handle network switching edge cases
Test with realistic gas prices and block times
Consider chain-specific wallet behaviors
Code Quality Expectations
Documentation Standards
Add JSDoc comments for public APIs
Include usage examples in complex functions
Document edge cases and error conditions
Update README.md for API changes
Testing Requirements
Write integration tests for new wallet actions
Test with all supported wallets when adding features
Include fork mode tests for DeFi interactions
Verify cross-browser compatibility
Performance Considerations
Optimize for test execution speed
Minimize unnecessary blockchain calls
Use efficient selectors in Playwright tests
Cache wallet extensions properly
Debugging Guidelines
Common Issues and Solutions
TypeScript Compilation Errors
Check that Node.js types are available
Verify Playwright test types are imported correctly
Ensure proper async/await typing
Wallet Extension Problems
Run preparation scripts to download extensions
Check file permissions on extension directories
Verify browser compatibility
Network Configuration Issues
Validate RPC URLs are accessible
Check chain ID matches network configuration
Ensure sufficient rate limits for fork mode
Effective Debugging Process
Reproduce the issue with minimal test case
Check browser developer tools for errors
Review wallet extension logs
Analyze network requests and blockchain calls
Test with different networks and configurations
Collaboration Guidelines
Code Review Focus
Verify TypeScript strict compliance
Check wallet action consistency across implementations
Ensure test coverage for new features
Review documentation completeness
Communication Style
Provide detailed explanations for complex blockchain concepts
Include code examples in technical discussions
Consider multiple perspectives on architectural decisions
Document reasoning behind implementation choices
Claude's Role in the Project
As Claude, you excel at:
Deep analysis of complex blockchain testing scenarios
Comprehensive planning for feature implementations
Thoughtful consideration of edge cases and error conditions
Clear documentation of complex technical concepts
Focus on leveraging these strengths while maintaining the project's focus on reliability, type safety, and comprehensive testing capabilities for blockchain DApps.copilot-instructions.md ## Pull Request Overview :
+## Quick Start Setup for GitHub Copilot
+
+### Step
+## Quick Start Setup for GitHub Copilot
+
+### Step 1: Repository Setup
+1. Clone the repository:
+1. Enable Copilot in your IDE (VS Code, IntelliJ, etc.)
+2. Load project context: Open the repository in your IDE to let Copilot understand the codebase
+3. Review instructions: Familiarize yourself with this file and the specialized instruction files in
.github/instructions/+### Step 3: AI Agent Setup (Optional)
+For advanced AI assistance, review the agent-specific documentation:
+- Claude: See
CLAUDE.mdfor Claude-specific instructions and focus areas+- Gemini: See
GEMINI.mdfor Gemini-specific strengths and workflows+- General: See
AGENTS.mdfor common AI agent guidelines+
+### Step 4: Environment Configuration
+1. Set required environment variables: @copilot @.github/copilot-instructions
Create .env file (never commit this)
Edit .env to add your E2E_TEST_SEED_PHRASE and any other secrets
+## Quick Start Setup for GitHub Copilot
+
+### Step 1: Repository Setup
+1. Clone the repository:
Edit .env to add your E2E_TEST_SEED_PHRASE and any other secrets
Current Documentation
Currently, there is no clear, consolidated documentation for Copilot and agent setup steps in the specified files:
.github/copilot-instructions.md.github/instructions/**/*.instructions.md**/AGENTS.md/CLAUDE.md/GEMINI.mdIssue Description
There is a lack of comprehensive setup steps and usage instructions for GitHub Copilot and agent integrations. This makes it difficult for new contributors or users to understand how to configure, use, and extend Copilot and the supported agents.
Suggested Improvement
Add step-by-step documentation covering:
.github/instructions/**/*.instructions.mdfilesUse Case
This would help new contributors and users:
Additional Context
Code Example (if applicable)
N/A
Environment (if reporting broken examples)
Checklist
AI: Thank you for the detailed feedback! Your suggestions are clear and actionable. Here’s a summary of what needs to be improved:
Documentation Issues Identified:
.envsetup steps (should usecp AI: .envinstead ofecho ... > .env).Missing or unclear documentation in:
AI:
.github/instructions/**/*.instructions.mdAI:
AI:
AI:
AI: (AI agent section)
Suggested Improvements:
.envsetup instructions.Next Steps:
AI: with a clear quick start, correct
.envsetup, and agent workflow examples.AI: ,
AI: , and
AI: with agent-specific setup, usage, and troubleshooting.
AI: references the new documentation and provides navigation.
.github/instructions/**/*.instructions.mdfor clarity and completeness.Would you like me to start by updating
AI: and then proceed to the other files, or do you have a preferred order?
User: implement this.
AI: Coding agent session cancelled.
User: implement this.
AI: Coding agent session cancelled.
User: implement this.
TITLE: Documentation Improvement for GitHub Copilot and AI Agents
USER INTENT: The user aims to enhance the documentation related to GitHub Copilot and AI agents, ensuring clarity and completeness for new contributors and users.
TASK DESCRIPTION: The user wants to address several documentation issues, including unclear setup instructions, outdated examples, and missing consolidated guides for using GitHub Copilot and AI agents. The goal is to create a comprehensive and user-friendly documentation structure.
EXISTING: The user has identified specific documentation files that require updates:
.github/copilot-instructions.md.github/instructions/**/*.instructions.mdAGENTS.mdCLAUDE.mdGEMINI.mdREADME.mdPENDING: The following updates are needed:
.github/copilot-instructions.mdto include a clear quick start guide, correct.envsetup instructions, and agent workflow examples.AGENTS.md,CLAUDE.md, andGEMINI.mdwith agent-specific setup, usage, and troubleshooting information.README.mdreferences the new documentation and provides clear navigation..github/instructions/**/*.instructions.mdfor clarity and completeness.CODE STATE:
.envsetup from:RELEVANT CODE/DOCUMENTATION SNIPPETS:
OTHER NOTES: The user has repeatedly requested the implementation of these documentation improvements, indicating a strong need for timely action. The assistant's coding agent session was cancelled, suggesting a need for a different approach to implement the changes.
Original prompt
implement this.
The following is a snapshot of a chat conversation between a user and an AI coding assistant. Prioritize later messages in the conversation.
User: - echo "E2E_TEST_SEED_PHRASE=your-test-seed-phrase-here" > .env
Edit .env to add your E2E_TEST_SEED_PHRASE and any other secrets
INFO: notify_waitpid_callback_by_pid: Child process 9573 has exited; no callback was registered
Documentation Issue Type
Location
Where is the documentation issue located?
/exampledirectory/docsdirectory.github/copilot-instructions.md).github/instructions/**/*.instructions.md)**/AGENTS.md)/CLAUDE.md)/GEMINI.md)AGENTS.md Enhanced with quick setup checklist, workflow examples, and agent-specific best practices
CLAUDE.md Added Claude-optimized setup workflow with analytical implementation examples
GEMINI.md Added rapid setup steps and performance-focused optimization examples
README.md Integrated new AI agent documentation section with clear navigation and quick start guideClaude AI Instructions for Onchain Test Kit
This document provides specific instructions for Claude when working on the Onchain Test Kit project. For general project context, also refer to AGENTS.md and .github/copilot-instructions.md.
Quick Setup for Claude
Initial Configuration Steps
Load project context: Familiarize yourself with the repository structure and existing patterns
Review dependencies: Understand the TypeScript, Playwright, and Viem ecosystem
Study wallet patterns: Examine existing wallet implementations for consistency
Test setup: Verify you can run the build and test pipeline
Claude's Optimal Usage Workflow
// 1. Analyze requirements thoroughly
// Example: Adding a new wallet action for token swaps
// 2. Research existing patterns
// Check how similar actions are implemented across wallets
// Review test patterns for comprehensive coverage
// 3. Plan implementation
interface SwapActionOptions {
shouldApprove: boolean;
tokenIn: string;
tokenOut: string;
amount: string;
slippage?: string;
}
// 4. Implement with error handling
async handleSwapAction(options: SwapActionOptions): Promise {
try {
const popup = await this.waitForPopup();
// Handle swap-specific UI interactions
await popup.getByTestId('swap-confirm').click();
} catch (error) {
throw new WalletActionError('Swap action failed', error);
}
}
// 5. Add comprehensive tests
test('token swap approval flow', async ({ page, metamask }) => {
// Test happy path
// Test rejection path
// Test error conditions
// Test with different token pairs
});
Claude-Specific Strengths and Focus Areas
Leverage Claude's Capabilities
Code reasoning: Use detailed analysis for complex blockchain testing scenarios
Pattern recognition: Identify and maintain consistent architectural patterns
Comprehensive explanations: Provide thorough documentation for complex wallet interactions
Edge case consideration: Think through various blockchain and wallet edge cases
Preferred Development Approach
When approaching tasks:
Analyze the full context of blockchain testing requirements
Consider wallet-specific behaviors and limitations
Think through async patterns and timing issues
Plan for cross-browser compatibility
2. Detailed Implementation Planning
Before making changes:
Review existing wallet implementations for patterns
Consider impact on all supported wallets (MetaMask, Coinbase, Phantom)
Plan for both unit tests and integration tests
Think through fork mode implications
3. Comprehensive Error Handling
Anticipate wallet connection timeouts
Handle network switching failures gracefully
Provide clear error messages for debugging
Consider retry mechanisms for flaky operations
Key Areas of Focus
Blockchain Testing Complexity
Fork mode testing: Understanding of mainnet forking for realistic testing
Multi-wallet scenarios: Handling different wallet behaviors consistently
Network switching: Chain-specific configurations and transitions
Transaction handling: Gas estimation, approval flows, and error states
TypeScript Excellence
Maintain strict typing throughout the codebase
Use proper generic constraints for wallet actions
Implement discriminated unions for action types
Ensure proper async/await typing ...
💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.