diff --git a/CLAUDE.md b/CLAUDE.md
index 44d05b0e..8e9bf4f0 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -8,27 +8,33 @@ Configuration-driven workflow orchestration engine built in Go on the [modular](
 
 ## Build & Run
 
+If a `go.work` file in a parent directory links this repo into a multi-repo
+workspace (common for GoCodeAlone contributors), prefix commands with
+`GOWORK=off` so the build resolves against this repo's own `go.mod`:
+
 ```sh
 # Build the server
-go build -o server ./cmd/server
+GOWORK=off go build -o server ./cmd/server
 ./server -config example/api-server-config.yaml
 
 # Build the CLI
-go build -o wfctl ./cmd/wfctl
+GOWORK=off go build -o wfctl ./cmd/wfctl
 ./wfctl validate example/api-server-config.yaml
 
 # Run tests
-go test ./...
-go test -race ./...
+GOWORK=off go test ./...
+GOWORK=off go test -race ./...
 
 # UI development
 cd ui && npm install && npm run dev
 
 # Lint
 go fmt ./...
-golangci-lint run
+GOWORK=off golangci-lint run
 ```
 
+(When developing this repo standalone, `GOWORK=off` is redundant but harmless.)
+
 ## Project Structure
 
 - `cmd/server/` — Server binary entry point
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 14cc3d6b..c6b605a1 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -13,18 +13,21 @@ Thank you for your interest in contributing to the workflow engine. This guide c
 
 ### Clone and Build
 
+If a parent directory contains a `go.work` file (multi-repo workspace),
+prefix Go commands with `GOWORK=off` to build against this repo's `go.mod`:
+
 ```bash
 git clone https://github.com/GoCodeAlone/workflow.git
 cd workflow
 
 # Build the server
-go build -o server ./cmd/server
+GOWORK=off go build -o server ./cmd/server
 
 # Run tests
-go test -race ./...
+GOWORK=off go test -race ./...
 
 # Run linter
-golangci-lint run
+GOWORK=off golangci-lint run
 
 # UI setup (optional)
 cd ui
@@ -69,10 +72,10 @@ docs/            API docs, tutorials, ADRs
 5. **Run the full check suite** before submitting:
 
 ```bash
-# Go checks
+# Go checks (prefix with GOWORK=off if you have a parent go.work file)
 go fmt ./...
-golangci-lint run
-go test -race ./...
+GOWORK=off golangci-lint run
+GOWORK=off go test -race ./...
 
 # UI checks (if UI changes)
 cd ui