You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@skywalking.apache.org by li...@apache.org on 2026/10/18 14:39:37 UTC

(skywalking-go) branch main updated: Add AGENTS.md with CLAUDE.md as a symlink, and build and plugin-e2e skills (#261)

This is an automated email from the ASF dual-hosted git repository.

mrproliu pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/skywalking-go.git


The following commit(s) were added to refs/heads/main by this push:
     new 7efac2c  Add AGENTS.md with CLAUDE.md as a symlink, and build and plugin-e2e skills (#261)
7efac2c is described below

commit 7efac2cdb9ce64e98e9adec9f624a079e1dcc136
Author: 吴晟 Wu Sheng <wu...@foxmail.com>
AuthorDate: Sun Oct 18 22:39:32 2026 +0800

    Add AGENTS.md with CLAUDE.md as a symlink, and build and plugin-e2e skills (#261)
---
 .agents/skills                     |   1 +
 .claude/skills/build/SKILL.md      | 140 ++++++++++++++++++++++++++++++
 .claude/skills/plugin-e2e/SKILL.md | 173 +++++++++++++++++++++++++++++++++++++
 .gitignore                         |   2 +
 .licenserc.yaml                    |   2 +
 AGENTS.md                          | 173 +++++++++++++++++++++++++++++++++++++
 CLAUDE.md                          |   1 +
 7 files changed, 492 insertions(+)

diff --git a/.agents/skills b/.agents/skills
new file mode 120000
index 0000000..454b842
--- /dev/null
+++ b/.agents/skills
@@ -0,0 +1 @@
+../.claude/skills
\ No newline at end of file
diff --git a/.claude/skills/build/SKILL.md b/.claude/skills/build/SKILL.md
new file mode 100644
index 0000000..05f6f91
--- /dev/null
+++ b/.claude/skills/build/SKILL.md
@@ -0,0 +1,140 @@
+---
+name: build
+description: Build the SkyWalking Go agent binary, run unit/race tests and lint, check the Go 1.26 floor, and compile an instrumented application to verify plugin code at both ends of a framework version range
+user-invocable: true
+allowed-tools: Bash, Read, Glob, Grep
+---
+
+# Build and Verify the SkyWalking Go Agent
+
+Infer what the user wants from the request or recent changes, then run the
+matching steps. Run the smallest relevant step first, and report each command
+with its result.
+
+## Prerequisites
+
+```bash
+go version                      # Go 1.26 or newer; CI uses 1.26 and 1.27
+git rev-parse --short HEAD      # the build version
+ls VERSION 2>/dev/null && cat VERSION   # see "Agent binary"
+```
+
+## Agent binary
+
+`make build` creates the gitignored `VERSION` file the first time and keeps using
+it, so the binary name can drift from the current commit. Pass the version
+explicitly:
+
+```bash
+make -C tools/go-agent build VERSION=$(git rev-parse --short HEAD)   # linux, darwin, windows
+make -C tools/go-agent darwin VERSION=$(git rev-parse --short HEAD)  # one platform
+ls bin/skywalking-go-agent-*
+```
+
+## Tests
+
+`make test` runs `go test` in every module it finds, except the plugin scenarios.
+That includes leftover scenario copies and nested worktrees, so remove those
+first:
+
+```bash
+rm -rf test/plugins/workspace
+make test             # every module except the plugin scenarios
+make test-race        # only TestRace*, under the race detector, outside test/
+(cd plugins/<name> && go test ./...)   # one module
+```
+
+Check the floor: a dependency that needs a newer Go fails here instead of in CI.
+
+```bash
+GOTOOLCHAIN=go1.26.<latest patch> go test ./...
+```
+
+## Lint and consistency
+
+`make lint` uses `$(go env GOPATH)/bin/golangci-lint`. It installs v2.15.0, the
+CI version, only when that binary is missing, and otherwise reuses whatever
+version is installed. Check that exact binary, not the one on `PATH`. The install
+URL matters: older copies of the install script fail the checksum check for
+releases with SBOMs.
+
+```bash
+LINT="$(go env GOPATH)/bin/golangci-lint"
+"$LINT" version
+curl -sSfL https://golangci-lint.run/install.sh | sh -s -- -b "$(go env GOPATH)/bin" v2.15.0
+make lint             # skips the plugin scenario and e2e modules
+(cd <module> && "$LINT" run --config "$(git rev-parse --show-toplevel)/.golangci.yml" ./...)
+make check            # root go mod tidy, then requires a clean working tree
+```
+
+`make check` fails on any uncommitted change, including ones that existed before
+it ran. `license-eye header check` (apache/skywalking-eyes) verifies the license
+headers of the files that `.licenserc.yaml` does not exclude.
+
+## Instrumented compile check
+
+Run this check after changing any code that the agent copies or injects into a
+framework: plugin interceptors, native mirrors, or the logger and runtime
+templates. Unit tests do not cover it. Copied files compile inside the framework
+package, where only that package's direct imports are available.
+
+Two rules for the commands below:
+- Build the agent inside the repository workspace, because `tools/go-agent`
+  resolves the plugin modules through `go.work`. Build the application outside
+  it.
+- Use a dedicated `GOCACHE`. Instrumented builds otherwise leave instrumented
+  package objects in the shared build cache, which later plain builds reuse.
+
+```bash
+set -euo pipefail     # stop before inspecting or running a stale app after a failed build
+REPO=$(git rev-parse --show-toplevel)
+WORK=$(mktemp -d)
+(cd "$REPO/tools/go-agent" &&
+  GOWORK="$REPO/go.work" GOFLAGS= GOCACHE="$WORK/gocache" go build -o "$WORK/agent" ./cmd)
+export GOWORK=off GOFLAGS=-mod=mod GOCACHE="$WORK/gocache"
+
+mkdir "$WORK/app" && cd "$WORK/app"
+cat > main.go <<'EOF'
+package main
+
+import (
+	_ "github.com/apache/skywalking-go"
+	// import the framework and call the hooked API, so the hook is compiled in
+)
+
+func main() {}
+EOF
+go mod init app
+go mod edit -replace=github.com/apache/skywalking-go="$REPO" \
+  -require=google.golang.org/genproto@v0.0.0-20230530153820-e85fd2cbaebc
+go get <framework module>@<version>
+go mod tidy
+go list -m <framework module>                 # the version actually selected
+go build -toolexec="$WORK/agent" -a -work -o app . 2>&1 | tee build.log
+go tool nm app | grep -F '<hooked package path>' | grep -F '<expected generated symbol>'
+SW_AGENT_REPORTER_GRPC_BACKEND_SERVICE=127.0.0.1:1 ./app
+```
+
+Verify the specific generated code of the change, because the agent itself links
+gRPC and a generic match proves nothing:
+- for a framework plugin, the interceptor of the hooked package, such as
+  `(*skywalking_operatorTypeRestfulAddFilterInterceptor).BeforeInvoke`;
+- for logger or runtime changes, which generate helpers rather than
+  interceptors, their specific generated symbols (for example
+  `skywalking_operatorStaticMethodLogrus...` or the runtime `_skywalking_*`
+  functions), or the rewritten source in the `WORK=` directory that
+  `build.log` prints.
+
+Repeat at the lowest and highest version of the plugin's range. For a version
+split, also check the boundary versions on both sides.
+
+Common failures:
+- `could not import X (open : no such file or directory)`: a copied file imports
+  a package that the hooked package does not import directly in that version.
+- `undefined: skywalking_operator...`: an identifier in a copied or injected file
+  was rewritten. In logger templates, prefer unnamed types to framework types.
+
+## Report
+
+Summarize the commands you ran and their pass or fail results. For failures,
+include the first compiler or test error, with its file and line.
diff --git a/.claude/skills/plugin-e2e/SKILL.md b/.claude/skills/plugin-e2e/SKILL.md
new file mode 100644
index 0000000..7f96207
--- /dev/null
+++ b/.claude/skills/plugin-e2e/SKILL.md
@@ -0,0 +1,173 @@
+---
+name: plugin-e2e
+description: Run SkyWalking Go plugin scenario tests and the end-to-end suite locally the way CI does, narrow a run to some framework versions, and diagnose build, dependency, runtime, and validation failures
+user-invocable: true
+allowed-tools: Bash, Read, Glob, Grep, Edit
+---
+
+# Run Plugin Scenario Tests and E2E Locally
+
+Ask which scenario to run if the user did not say, or infer it from the changed
+plugins. A run of several cases takes minutes, so run it in the background and
+report when it ends.
+
+Scenario names usually match the plugin directory, with these exceptions:
+
+| Plugin | Scenario |
+|---|---|
+| `grpc`, `grpc-v184` | `grpc` |
+| `dubbo`, `dubbo-v331` | `dubbo` |
+| `runtimemetrics` | `runtime_metrics` |
+| `sql` | `mysql`, `postgres` |
+| `gorm` | `gorm` (MySQL driver), `gorm-postgres` (PostgreSQL driver) |
+| `toolkit-activation` | `trace-activation`, `logging-activation`, `metric-activation`, `cross-goroutine` |
+| logrus/zap logger (`tools/go-agent/instrument/logger`) | `logrus`, `zap` |
+
+## Prerequisites
+
+```bash
+docker info >/dev/null && echo docker ok
+docker-compose version --short    # the scenario scripts call docker-compose
+yq --version                      # mikefarah yq v4, used by run.sh
+go version
+```
+
+## 1. Build the test tools
+
+Rebuild after every change to the agent, a plugin, or the runner. This builds the
+linux agent for the host architecture, the runner-helper, and the validator
+image. Pass `VERSION`, because a stale gitignored `VERSION` file would make the
+build look for a binary name that does not exist.
+
+```bash
+make -C test/plugins build VERSION=$(git rev-parse --short HEAD)
+```
+
+## 2. Run a scenario
+
+Write the whole output to a file outside the workspace. Validator failures and
+some build errors go to the command's output only, not to the case logs.
+
+```bash
+bash test/plugins/run.sh <scenario> > /tmp/<scenario>.log 2>&1
+bash test/plugins/run.sh --debug <scenario> > /tmp/<scenario>.log 2>&1   # keep workspace and actual data
+```
+
+Each `support-version` entry in `plugin.yml` produces one case per framework
+version, `go<version>-<framework version>`. Scenarios with `framework: go` have no
+framework list and run one `go<version>-native` case per entry. The run stops at
+the first failing case. Success ends with `Scenarios: <name>, Testcases: N`.
+
+`bash test/plugins/run.sh --clean` is a global cleanup:
+- it removes all dangling Docker images and prunes unused networks and volumes;
+- it deletes `test/plugins/dist` and `test/plugins/workspace`.
+
+Run `--clean` on its own, then rebuild the test tools (step 1) before running a
+scenario. It currently exits non-zero when `test/plugins/workspace` was already
+absent. With a scenario name, a successful cleanup continues into that scenario,
+which then fails because `dist/runner-helper` was deleted.
+
+To run only some versions, save the scenario's `plugin.yml`, edit it, run, then
+restore the saved copy. The saved copy keeps any changes made before the run.
+Never commit a narrowed matrix.
+
+```bash
+cp test/plugins/scenarios/<scenario>/plugin.yml /tmp/<scenario>-plugin.yml
+# edit test/plugins/scenarios/<scenario>/plugin.yml, then run the scenario
+cp /tmp/<scenario>-plugin.yml test/plugins/scenarios/<scenario>/plugin.yml
+```
+
+## 3. Diagnose failures
+
+A failed case keeps `test/plugins/workspace/<scenario>/<case>/logs/`:
+- `service.log`: the service container's standard output. This includes
+  `bin/startup.sh`, where the instrumented build and the application run.
+- `scenarios.log` and `runner-helper.log`: the standard output of the scenario
+  script, which includes the image build with `go mod tidy`, and of the
+  runner-helper.
+
+Compiler errors, panics, and validation reasons can appear only in the run output
+you saved in step 2, so check that first.
+
+| Symptom | Usual cause |
+|---|---|
+| `failed to solve: ... go mod tidy` | The case's framework version does not resolve with the scenario's other requirements, or a dependency needs a newer Go. Reproduce it as described in section 4. |
+| `could not import X (open : no such file or directory)` | A copied plugin file imports a package that the hooked package does not import directly in that version. See the `build` skill and `AGENTS.md`. |
+| `undefined: skywalking_operator...` | An identifier in copied or injected code was rewritten. |
+| `panic` at startup | The application fails before serving, for example a protobuf `file "x.proto" is already registered` conflict. Give the scenario's proto file a unique name. |
+| `[ERROR] <case>, validate actual data failed!` | The reported data differs from `config/excepted.yml`. The `reason:` line names the first mismatch, such as a component id, or `ActualSegmentRefIsEmptyException` when context propagation is missing. |
+
+When a framework version legitimately reports different data, add an
+expectation file and set `excepted-file: config/<file>.yml` on that version's
+`support-version` entry. Do not loosen the shared expectation file.
+
+## 4. Check what a case actually builds
+
+`run.sh` rewrites the `framework:` requirement in the case's `go.mod`. The
+Dockerfile then adds the local agent `replace` (plus the toolkit one when
+`toolkit: true`) and a genproto requirement, and runs `go mod tidy` with
+`GOWORK=off` inside the image. The scenario's own requirements can still lift
+the framework version. The host workspace copy does not contain these edits, so
+check the built image, which holds the last case that built successfully. Its name
+is `<project>-service` with Compose v2 and `<project>_service` with Compose v1
+(`docker-compose version --short`). `<project>` is the scenario name in lower
+case with the dots removed.
+
+```bash
+docker run --rm --entrypoint go <project>-service list -m <framework module>
+```
+
+To reproduce on the host instead, use a temporary copy of the scenario:
+1. set its `go` line and framework version the way `run.sh` does;
+2. apply the Dockerfile's edits, with absolute paths instead of its
+   container-relative ones;
+3. run `go mod tidy` and `go list -m` with the case's Go version.
+
+```bash
+REPO=$(git rev-parse --show-toplevel)    # before entering the temporary copy
+export GOWORK=off
+go mod edit -replace=github.com/apache/skywalking-go="$REPO" \
+  -require=google.golang.org/genproto@v0.0.0-20230530153820-e85fd2cbaebc
+go mod edit -replace=github.com/apache/skywalking-go/toolkit="$REPO/toolkit"   # only with toolkit: true
+go mod tidy && go list -m <framework module>
+```
+
+`framework:` must be the module path exactly as written in `go.mod`, including a
+`/vN` suffix. Otherwise every case builds the version pinned in `go.mod`.
+
+## 5. Adding or changing versions
+
+1. Add the version to `plugin.yml`: the oldest Go entry for the floor, plus a
+   newest-Go entry for the latest version.
+2. Bump the plugin module's framework requirement in `plugins/<name>/go.mod` when
+   the new version becomes the newest one.
+3. Run the scenario.
+4. Update `docs/en/agent/support-plugins.md` so the range is the tested min..max,
+   and add a `CHANGES.md` entry at the end of the matching section.
+5. List a new scenario in the `case` matrix of
+   `.github/workflows/plugin-tests.yaml`.
+
+The Docker scenarios run on ubuntu amd64 in CI. Local runs on arm64 do not
+exercise amd64-only code paths in frameworks, so CI is the final check. The
+separate Windows workflow builds the `http` scenario on the host with
+`windows-scenarios.tpl`, without containers or `GOWORK=off`.
+
+## 6. End-to-end suite
+
+`test/e2e` runs the reporter cases (`grpc`, `grpc-multi-backend`, `kafka`) with
+skywalking-infra-e2e. Install the CLI at the same commit as
+`.github/workflows/e2e.yaml`, into an explicit directory, and run that binary from
+the repository root:
+
+```bash
+make -C test/e2e build VERSION=$(git rev-parse --short HEAD)
+GOBIN=/tmp/skywalking-infra-e2e/bin go install \
+  github.com/apache/skywalking-infra-e2e/cmd/e2e@7e4b5b68716fdb7b79b21fa8908f9db497e1b115
+/tmp/skywalking-infra-e2e/bin/e2e run -c test/e2e/case/grpc/e2e.yaml --batch-mode=true
+```
+
+## Report
+
+List each case with pass or fail. For a failure, give the case name, where the
+error appeared (the run output or a log file), the first relevant error or
+`reason:` line, and the likely cause from the table.
diff --git a/.gitignore b/.gitignore
index 1ca07e2..f8fb3f1 100644
--- a/.gitignore
+++ b/.gitignore
@@ -11,3 +11,5 @@ coverage.txt
 /tools/protocols/temp/
 vendor/
 VERSION
+.claude/worktrees/
+.claude/settings.local.json
diff --git a/.licenserc.yaml b/.licenserc.yaml
index 8f1e126..f425358 100644
--- a/.licenserc.yaml
+++ b/.licenserc.yaml
@@ -24,6 +24,8 @@ header:
 
   paths-ignore:
     - '**/*.md'
+    # Symlink to .claude/skills; the pinned license-eye recurses forever on directory symlinks.
+    - '.agents/skills'
     - 'licenses'
     - '**/go.mod'
     - '**/go.sum'
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..fbc516d
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,173 @@
+# SkyWalking Go Agent Guide
+
+Apache SkyWalking Go is a compile-time auto-instrumentation agent. The
+`skywalking-go-agent` binary runs as `go build -toolexec`, rewrites the
+framework packages an application uses, and links the agent runtime into the
+application. Follow nearby code and tests, and keep changes focused on the
+requested behavior.
+
+## Repository layout
+
+- The root module `github.com/apache/skywalking-go` (`agent/`, `log/`,
+  `imports.go`) is what applications import with
+  `_ "github.com/apache/skywalking-go"`. Its `go` directive becomes the minimum Go
+  version of every application that imports it.
+- `plugins/core` holds the tracing core and the plugin API (`instrument`,
+  `operator`, `tracing`). It is compiled into the application.
+- `plugins/<name>`: one Go module per framework plugin. Some frameworks have
+  version-split plugins, such as `grpc` and `grpc-v184`, or `dubbo` and
+  `dubbo-v331`.
+- `tools/go-agent` builds the `skywalking-go-agent` toolexec binary. Plugins are
+  registered in `tools/go-agent/instrument/plugins/register.go`. The runtime
+  hook (`instrument/runtime`) and the logrus/zap integration
+  (`instrument/logger`) live here too.
+- `toolkit` is the public toolkit API. `test/plugins` holds the plugin scenario
+  tests, `test/e2e` the end-to-end suite, and `docs/` the documentation.
+- `go.work` lists the agent, toolkit, tools, plugin modules, and most test
+  modules. Plugin scenario cases are built with `GOWORK=off` (see below).
+
+## Skills
+
+Task skills live in `.claude/skills/<name>/SKILL.md`: `build` for building,
+testing, and linting, and `plugin-e2e` for plugin scenario and e2e tests.
+`.agents/skills` is a symlink to the same directory, so other agents such as
+Codex discover the same skills. Edit the files under `.claude/skills`.
+`CLAUDE.md` is a symlink to this file. Both aliases need a checkout with
+symlink support (`core.symlinks`); without it, read `AGENTS.md` and
+`.claude/skills` directly.
+
+## Go versions
+
+- The floor is Go 1.26: the agent, toolkit, tools, and plugin modules declare
+  `go 1.26.0`. Scenario and e2e fixture modules keep older `go` lines:
+  `test/plugins/run.sh` rewrites each plugin case's `go` line, and the e2e
+  fixtures get their Go version from their Dockerfiles. CI builds and tests with
+  Go 1.26 and Go 1.27.
+- Keep the floor at the oldest Go release that is still supported upstream,
+  because raising the root module's `go` line forces every user application to
+  that Go version.
+- A dependency must not require a newer Go than the floor. Run `go get` with
+  `GOTOOLCHAIN=go1.26.<latest>` so that such a dependency fails locally.
+
+## Build, test, and lint
+
+See `.claude/skills/build/SKILL.md` for the details. In short:
+
+- `make build` builds `bin/skywalking-go-agent-<VERSION>-{linux,darwin,windows}-<arch>`.
+- `make test` runs the tests of every module except the plugin scenarios.
+- `make test-race` runs only the `TestRace*` tests, under the race detector, and
+  skips the modules under `test/`.
+- `make lint` runs golangci-lint, using the repository `.golangci.yml`, in every
+  module except the plugin scenarios and e2e modules. Its installer is pinned to
+  v2.15.0, but an existing `$(go env GOPATH)/bin/golangci-lint` is reused.
+- `make check` runs `go mod tidy` in the root module only, then requires a clean
+  working tree, so it also fails on edits that existed before.
+
+## Writing plugins
+
+These rules come from how the agent rewrites code. Ignoring them breaks user
+builds, sometimes only at one end of a version range.
+
+- **Selection.** For each compiled package, the agent uses the first registered
+  instrument whose `BasePackage()` is a prefix of the package and whose
+  `VersionChecker(version)` accepts the module version. The version comes from
+  `vendor/modules.txt` or the module cache path. It is empty when the framework
+  is replaced by a local module.
+- **Copied files.** Every non-test `.go` file of the plugin package directory is
+  copied into the framework package and compiled there. Files containing
+  `//skywalking:nocopy` (such as `instrument.go`), `//skywalking:native`, or
+  `//skywalking:ref_generate` are not copied; the agent only reads the mappings
+  from the last two. Do not put helpers in those files.
+- **Imports.** A copied file can only import packages that the hooked package
+  imports directly, standard library packages included, in every supported
+  version. The agent rewrites only two kinds of imports: the hooked package
+  itself, and `github.com/apache/skywalking-go/plugins/core/{operator,log,tracing,tools,metrics,profile}`.
+- **Native mirrors.** `//skywalking:native <pkg> <Type>` declares a mirror struct
+  that is rewritten to the real framework type. Its field names and types must
+  exist in every version the plugin accepts.
+- **Matching.** For receiver methods, matching compares only the method name and
+  receiver type; `WithArgType`/`WithResultType` filters apply to static
+  functions only. A signature change therefore still matches, and fails at
+  runtime in the interceptor's `invocation.Args()[i]` type assertions. Use
+  checked type assertions.
+- **Version splits.** When a framework release changes the internals the
+  interceptors compile against, add a separate plugin folder rather than
+  version branches in one folder:
+  - give the two plugins disjoint `VersionChecker`s and the same `Name()`, so
+    that plugin exclusion keeps working;
+  - let the legacy plugin accept unparseable versions.
+- **Plugin `go.mod`.** It requires the newest verified framework version. It does
+  not affect user builds or scenario cases, but it is linked into the agent
+  binary, so keep it free of vulnerable dependencies (`govulncheck` on
+  `tools/go-agent`).
+- **Logger code.** Code in `tools/go-agent/instrument/logger/frameworks` is
+  injected into logrus/zap by AST rewriting. References to the framework package,
+  such as `logrus.Fields`, are rewritten, so prefer an unnamed equivalent type
+  such as `map[string]interface{}`.
+
+### Bumping a framework version
+
+1. Check that every hook point of the plugin exists with the same full signature
+   at the lowest and highest supported version.
+2. Compile a small instrumented application at both ends:
+   `go build -toolexec=<agent> -a` with `GOWORK=off` and
+   `replace github.com/apache/skywalking-go => <repo>`.
+3. Run the scenario (`.claude/skills/plugin-e2e/SKILL.md`).
+4. Update the scenario `plugin.yml`, the plugin `go.mod`,
+   `docs/en/agent/support-plugins.md` (the ranges must equal the tested
+   min..max), and `CHANGES.md`.
+
+## Plugin tests
+
+See `.claude/skills/plugin-e2e/SKILL.md` for running them. Key semantics:
+
+- Each `test/plugins/scenarios/<name>/plugin.yml` lists `support-version`
+  entries. Each entry has a Go version, framework versions, and an optional
+  `excepted-file` when a version changes the reported data.
+- `framework:` must be the module path exactly as written in the scenario
+  `go.mod`, including a `/vN` suffix. Otherwise the per-case version is silently
+  not applied. Scenarios with `framework: go` have no external framework version
+  to vary, which covers standard-library, agent, and toolkit scenarios: their
+  entries have no framework list, and each case is named `go<version>-native`.
+- In the Docker scenario workflow, each case builds with `GOWORK=off`, with the
+  agent replaced by the local code. The separate Windows workflow builds the
+  `http` scenario on the host through `windows-scenarios.tpl`, which does not set
+  `GOWORK=off`.
+  Set `toolkit: true` when the test code imports the toolkit. Older versions can
+  still be lifted by the scenario's own dependencies, so check the selected
+  version (`go list -m`) when adding a lower bound.
+- New scenarios must be added to the matrix in
+  `.github/workflows/plugin-tests.yaml`.
+
+## Changes, docs, and pull requests
+
+- Add `CHANGES.md` entries at the end of the matching section of the unreleased
+  version. When dropping support for library versions, list them, with the
+  reason, in the version's "Unsupported Library Versions" table.
+- New files that `.licenserc.yaml` does not exclude need the Apache license
+  header, checked by `license-eye`. Excluded files include Markdown, `go.mod`,
+  `go.sum`, `go.work`, and the protocol sources.
+  The license-eye version that CI pins recurses forever on directory symlinks,
+  so list every directory symlink, such as `.agents/skills`, in `paths-ignore`.
+- In `.github/workflows`, `apache/*`, `actions/*`, and `github/*` actions are
+  allowed. Third-party actions must be pinned to a commit SHA that is on the ASF
+  allow-list (apache/infrastructure-actions).
+- Pull requests are squash-merged. Keep one focused change per pull request, and
+  never commit `bin/`, `test/plugins/workspace/`, `VERSION`, or `.claude/worktrees/`.
+
+## Pitfalls
+
+- `make build` creates a gitignored `VERSION` file once and keeps using it, so
+  the binary name can drift from the commit that `test/plugins` and `test/e2e`
+  expect. Delete `VERSION`, or pass `VERSION=$(git rev-parse --short HEAD)` to
+  make.
+- `-toolexec` builds can leave instrumented package objects in the shared Go
+  build cache, which later plain builds and tests pick up. Run instrumented
+  builds with a dedicated `GOCACHE`. If a plain test's stack trace shows
+  `skywalking_operator...` symbols, run `go clean -cache`.
+- `make test` and `make lint` find every `go.mod` in the tree, including those in
+  `test/plugins/workspace/` (left by `--debug` or failed scenario runs) and in
+  nested worktrees such as `.claude/worktrees/`. Remove them first, or run from a
+  checkout without them.
+- `make lint` reuses any `golangci-lint` already in `$(go env GOPATH)/bin`, so
+  check `"$(go env GOPATH)/bin/golangci-lint" version` first.
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 120000
index 0000000..47dc3e3
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1 @@
+AGENTS.md
\ No newline at end of file