diff --git a/.env.template b/.env.template
index fac7424..de9a8be 100644
--- a/.env.template
+++ b/.env.template
@@ -2,8 +2,6 @@ BITBUCKET_MCP_EMAIL=your_email@example.com
 BITBUCKET_MCP_TOKEN=your_api_token
 DEFAULT_WORKSPACE=your-workspace
 DEFAULT_REPO=your-repo
-RUN_WRITE_TESTS=true
-TEST_PR_ID=123
 
 # Integration test write operations
 # ---------------------------------------------------------------------------------
@@ -12,7 +10,6 @@ TEST_PR_ID=123
 # TEST_PR_ID must also be set — write tests will only run against this specific PR
 # to avoid accidentally modifying unrelated pull requests.
 # ---------------------------------------------------------------------------------
-# Example:
 # RUN_WRITE_TESTS=true
 # TEST_PR_ID=123
 # ---------------------------------------------------------------------------------
diff --git a/CLAUDE.md b/CLAUDE.md
index 5c48210..27fe74c 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -43,7 +43,13 @@ The server is a 3-layer pipeline: **MCP protocol** -> **Router** -> **Bitbucket
 | `BITBUCKET_MCP_TOKEN` | Bitbucket API token (Basic Auth password) |
 | `DEFAULT_WORKSPACE` | Optional default workspace slug |
 | `DEFAULT_REPO` | Optional default repository slug |
+| `RUN_WRITE_TESTS` | Set to `true` to enable write integration tests |
+| `TEST_PR_ID` | PR ID to use for write integration tests (required when `RUN_WRITE_TESTS=true`) |
+
+Copy `.env.template` to `.env` and fill in your values for local development and testing.
 
 ## Testing
 
 Tests use vitest with 30s timeouts. Unit tests mock the Bitbucket client; integration tests call the real API and require valid credentials in the environment.
+
+Write integration tests (approve/unapprove, comments, tasks) are skipped by default. They require both `RUN_WRITE_TESTS=true` and `TEST_PR_ID` to be set. Write tests never pick a random PR — if `TEST_PR_ID` is missing the test is skipped with a warning.
diff --git a/README.md b/README.md
index 2aa0e7b..d8975c6 100644
--- a/README.md
+++ b/README.md
@@ -225,13 +225,17 @@ Response:
 
 ### Running Locally
 
-For development, you can use a `.env` file instead of configuring credentials in the MCP client:
+For development, you can use a `.env` file instead of configuring credentials in the MCP client. Copy `.env.template` to `.env` and fill in your values:
 
 ```env
 BITBUCKET_MCP_EMAIL=your_email@example.com
 BITBUCKET_MCP_TOKEN=your_api_token
 DEFAULT_WORKSPACE=my-workspace
 DEFAULT_REPO=my-repo
+
+# Only needed when running write integration tests (see Testing below)
+# RUN_WRITE_TESTS=true
+# TEST_PR_ID=123
 ```
 
 ```bash
@@ -261,14 +265,14 @@ npx tsc --noEmit
 npm run test:coverage
 ```
 
-**Write operation tests** (approve/unapprove, comments, tasks) are disabled by default. To enable them, set two variables in your `.env`:
+**Write operation tests** (approve/unapprove, comments, tasks) are disabled by default and require two additional variables in your `.env`:
 
-```env
-RUN_WRITE_TESTS=true
-TEST_PR_ID=123   # ID of a PR you own and can safely modify
-```
+| Variable | Description |
+|----------|-------------|
+| `RUN_WRITE_TESTS=true` | Opt in to running write tests |
+| `TEST_PR_ID=<id>` | ID of a PR you own and can safely modify |
 
-`TEST_PR_ID` is required — write tests will not fall back to a random PR. If it is not set, each write test is skipped with a warning. This prevents accidental modifications to production PRs.
+`TEST_PR_ID` is mandatory — write tests will never fall back to a random PR from the repository. If it is not set, each write test is skipped with a warning. This prevents accidental modifications to PRs you don't intend to touch.
 
 ### Project Structure