Create AI coding agent instructions for OpenTelemetry Java Instrumentation

[Copilot]

Updated the agent instructions to follow the agents.md format standard to generalize for any AI coding agent, not just GitHub Copilot.

Plan

• Analyze repository structure and existing documentation
• Test and measure build command times and structure
• Document exact bootstrap/setup requirements
• Document complete build process and validate timings
• Document testing scenarios and expected times
• Create instrumentation-specific documentation workflow
• Document code quality tools (spotless, license checks, muzzle)
• Document common navigation patterns and key directories
• Create final comprehensive instructions file
• Convert to agents.md format for agent-agnostic usage
• Address PR feedback and corrections

Completed Work

• Analyzed repository structure: 500+ modules across ~649 lines in settings.gradle.kts
• Validated build timings through testing actual Gradle commands
• Documented Java 21 requirement and multi-JVM testing matrix
• Measured configuration phase (60-90 seconds) and full build times (20-45 minutes)
• Tested code quality tools and muzzle functionality
• Renamed file from copilot-instructions.md to agents.md to follow standard format
• Addressed PR feedback:
  • Updated telemetry collection to use ci-collect.sh for better parallelism
  • Removed unnecessary removeJarVersionNumbers configuration
  • Updated ./gradlew test description and added ./gradlew check command
  • Removed -Ddev=true flag from test commands where not needed
  • Emphasized use of AssertJ and JUnit 5 testing frameworks
  • Updated environment variable usage guidance
• Created comprehensive instructions covering:
  • Build and test workflows with accurate timing estimates
  • Repository navigation for 500+ instrumentation modules
  • Development workflows for instrumentations
  • Critical timeout warnings to prevent premature cancellation
  • Common troubleshooting scenarios and network limitations
  • Extension development patterns
  • CI/CD integration patterns

Key Features

• Agent-agnostic format following agents.md standard
• Accurate build time estimates based on actual testing
• "NEVER CANCEL" warnings with specific timeout recommendations
• Step-by-step instrumentation development workflow
• Common command patterns with validated syntax
• Repository structure guidance for navigating 500+ modules
• Network limitation documentation for sandboxed environments
• Updated testing guidance emphasizing AssertJ and JUnit 5

The instructions are now generalized to work with any AI coding agent, not just GitHub Copilot, while maintaining all the technical accuracy and comprehensive guidance. All feedback from reviewers has been addressed.

Fixes #14769.

---

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

[jaydeluca]

@copilot use the agents.md format (https://agents.md/) in your output as to generalize for any agent, not just copilot

[Copilot]

@copilot use the agents.md format (https://agents.md/) in your output as to generalize for any agent, not just copilot

Converted to agents.md format as requested. Renamed the file from copilot-instructions.md to agents.md and the content is now agent-agnostic, suitable for any AI coding agent. Commit: 717ea0a

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• agents.md
  • Triggering command: curl -s REDACTED (dns block)
  • Triggering command: curl -s --max-time 10 REDACTED (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

[otelbot-java-instrumentation]

🔧 The result from generateLicenseReport was committed to the PR branch.

[steverao]

I'm curious why this PR was closed? If we can improve the instructions, for example, by documenting things to note when developing new instrumentations or things to keep in mind when reviewing code, we might be able to solve the current problem of insufficient manpower for code review.

[jaydeluca]

@steverao I closed it because it was getting old without any movement for a couple months, and we hadn't been using copilot for code reviews, so figured we could just re-open if there was a need for it in the future. Also I think the contents are questionable in terms of how valuable they are, but it might be an ok starting point to iterate on. Happy to re-open this, or start a new one if we want

[trask]

sorry for not commenting, still getting a handle on it all. In general copilot seems to get a lot of the basics fine on its own, and so I'd suggest limiting the agent instructions to known issues (to not clutter the context, which has downsides other than just token usage).

e.g. I have just these two instructions locally because copilot (well, the models I'm using?) get these wrong a lot for me:

# Java

Always import classes when possible (i.e. don't use fully qualified class names in code).

# Gradle CLI

Never use the `--rerun-tasks` flag unless explicitly asked to use this option.

Gradle automatically detects changes and re-runs tasks automatically when needed. Using `--rerun-tasks` is wasteful and slows down builds unnecessarily.

(and even with these, it did both of these things to me today, so 🤷)