diff --git a/docs/setup-github.ja.md b/docs/setup-github.ja.md
index da0a7d0..ca252a5 100644
--- a/docs/setup-github.ja.md
+++ b/docs/setup-github.ja.md
@@ -33,18 +33,21 @@ pnpm install
 ```json
 {
   "scriptId": "YOUR_SCRIPT_ID",
+  "projectId": "YOUR_GCP_PROJECT_ID",
   "rootDir": "dist"
 }
 ```
 
+> **`projectId`** は Apps Script に紐づく GCP プロジェクト**番号**です（`"123456789"` のような数字列。`my-project-abc` のようなプロジェクト ID ではない）。Apps Script エディタ → プロジェクトの設定 → Google Cloud Platform（GCP）プロジェクトで確認できます。記載することで GCP プロジェクトの紐づけが宣言的・再現可能になります。省略時は clasp がスクリプトの既存 GCP プロジェクトを使用します。
+
 ### 3. GitHub Environments の設定
 
-| Environment   | Secret / Variable         | 値                                        |
-| ------------- | ------------------------- | ----------------------------------------- |
-| `development` | Secret: `CLASP_JSON`      | `{"scriptId":"DEV_ID","rootDir":"dist"}`  |
-| `development` | Variable: `DEPLOYMENT_ID` | dev のデプロイメント ID                   |
-| `production`  | Secret: `CLASP_JSON`      | `{"scriptId":"PROD_ID","rootDir":"dist"}` |
-| `production`  | Variable: `DEPLOYMENT_ID` | prod のデプロイメント ID                  |
+| Environment   | Secret / Variable         | 値                                                                 |
+| ------------- | ------------------------- | ------------------------------------------------------------------ |
+| `development` | Secret: `CLASP_JSON`      | `{"scriptId":"DEV_ID","projectId":"GCP_NUM","rootDir":"dist"}`     |
+| `development` | Variable: `DEPLOYMENT_ID` | dev のデプロイメント ID                                            |
+| `production`  | Secret: `CLASP_JSON`      | `{"scriptId":"PROD_ID","projectId":"GCP_NUM","rootDir":"dist"}`    |
+| `production`  | Variable: `DEPLOYMENT_ID` | prod のデプロイメント ID                                           |
 
 ### 4. 確認とデプロイ
 
diff --git a/docs/setup-github.md b/docs/setup-github.md
index 3848a34..5128765 100644
--- a/docs/setup-github.md
+++ b/docs/setup-github.md
@@ -33,18 +33,21 @@ Create `.clasp-dev.json` and `.clasp-prod.json` (gitignored):
 ```json
 {
   "scriptId": "YOUR_SCRIPT_ID",
+  "projectId": "YOUR_GCP_PROJECT_ID",
   "rootDir": "dist"
 }
 ```
 
+> **`projectId`** is the GCP project **number** associated with your Apps Script (a numeric string like `"123456789"`, not the alphanumeric project ID like `my-project-abc`). Find it in Apps Script editor → Project Settings → Google Cloud Platform (GCP) Project. Including it makes the GCP project association declarative and reproducible. If omitted, clasp uses the script's existing GCP project.
+
 ### 3. Configure GitHub environments
 
-| Environment   | Secret / Variable         | Value                                     |
-| ------------- | ------------------------- | ----------------------------------------- |
-| `development` | Secret: `CLASP_JSON`      | `{"scriptId":"DEV_ID","rootDir":"dist"}`  |
-| `development` | Variable: `DEPLOYMENT_ID` | Your dev deployment ID                    |
-| `production`  | Secret: `CLASP_JSON`      | `{"scriptId":"PROD_ID","rootDir":"dist"}` |
-| `production`  | Variable: `DEPLOYMENT_ID` | Your prod deployment ID                   |
+| Environment   | Secret / Variable         | Value                                                              |
+| ------------- | ------------------------- | ------------------------------------------------------------------ |
+| `development` | Secret: `CLASP_JSON`      | `{"scriptId":"DEV_ID","projectId":"GCP_NUM","rootDir":"dist"}`     |
+| `development` | Variable: `DEPLOYMENT_ID` | Your dev deployment ID                                             |
+| `production`  | Secret: `CLASP_JSON`      | `{"scriptId":"PROD_ID","projectId":"GCP_NUM","rootDir":"dist"}`    |
+| `production`  | Variable: `DEPLOYMENT_ID` | Your prod deployment ID                                            |
 
 ### 4. Verify and deploy
 
diff --git a/docs/setup-gitlab.ja.md b/docs/setup-gitlab.ja.md
index f88b7c8..a87b029 100644
--- a/docs/setup-gitlab.ja.md
+++ b/docs/setup-gitlab.ja.md
@@ -83,20 +83,23 @@ pnpm install
 ```json
 {
   "scriptId": "YOUR_SCRIPT_ID",
+  "projectId": "YOUR_GCP_PROJECT_ID",
   "rootDir": "dist"
 }
 ```
 
+> **`projectId`** は Apps Script に紐づく GCP プロジェクト**番号**です（`"123456789"` のような数字列。`my-project-abc` のようなプロジェクト ID ではない）。Apps Script エディタ → プロジェクトの設定 → Google Cloud Platform（GCP）プロジェクトで確認できます。記載することで GCP プロジェクトの紐づけが宣言的・再現可能になります。省略時は clasp がスクリプトの既存 GCP プロジェクトを使用します。
+
 ### 3. CI/CD Variables の設定
 
 Settings → CI/CD → Variables で以下を追加：
 
-| 変数            | Environment scope | 値                                        | オプション |
-| --------------- | ----------------- | ----------------------------------------- | ---------- |
-| `CLASP_JSON`    | `development`     | `{"scriptId":"DEV_ID","rootDir":"dist"}`  | Masked     |
-| `CLASP_JSON`    | `production`      | `{"scriptId":"PROD_ID","rootDir":"dist"}` | Masked     |
-| `DEPLOYMENT_ID` | `development`     | dev のデプロイメント ID                   |            |
-| `DEPLOYMENT_ID` | `production`      | prod のデプロイメント ID                  |            |
+| 変数            | Environment scope | 値                                                                 | オプション |
+| --------------- | ----------------- | ------------------------------------------------------------------ | ---------- |
+| `CLASP_JSON`    | `development`     | `{"scriptId":"DEV_ID","projectId":"GCP_NUM","rootDir":"dist"}`     | Masked     |
+| `CLASP_JSON`    | `production`      | `{"scriptId":"PROD_ID","projectId":"GCP_NUM","rootDir":"dist"}`    | Masked     |
+| `DEPLOYMENT_ID` | `development`     | dev のデプロイメント ID                                            |            |
+| `DEPLOYMENT_ID` | `production`      | prod のデプロイメント ID                                           |            |
 
 ### 4. Template Sync の設定
 
diff --git a/docs/setup-gitlab.md b/docs/setup-gitlab.md
index ee735c0..00ec1b3 100644
--- a/docs/setup-gitlab.md
+++ b/docs/setup-gitlab.md
@@ -83,20 +83,23 @@ Create `.clasp-dev.json` and `.clasp-prod.json` (gitignored):
 ```json
 {
   "scriptId": "YOUR_SCRIPT_ID",
+  "projectId": "YOUR_GCP_PROJECT_ID",
   "rootDir": "dist"
 }
 ```
 
+> **`projectId`** is the GCP project **number** associated with your Apps Script (a numeric string like `"123456789"`, not the alphanumeric project ID like `my-project-abc`). Find it in Apps Script editor → Project Settings → Google Cloud Platform (GCP) Project. Including it makes the GCP project association declarative and reproducible. If omitted, clasp uses the script's existing GCP project.
+
 ### 3. Configure CI/CD Variables
 
 Go to Settings → CI/CD → Variables and add:
 
-| Variable        | Environment scope | Value                                     | Options |
-| --------------- | ----------------- | ----------------------------------------- | ------- |
-| `CLASP_JSON`    | `development`     | `{"scriptId":"DEV_ID","rootDir":"dist"}`  | Masked  |
-| `CLASP_JSON`    | `production`      | `{"scriptId":"PROD_ID","rootDir":"dist"}` | Masked  |
-| `DEPLOYMENT_ID` | `development`     | Your dev deployment ID                    |         |
-| `DEPLOYMENT_ID` | `production`      | Your prod deployment ID                   |         |
+| Variable        | Environment scope | Value                                                              | Options |
+| --------------- | ----------------- | ------------------------------------------------------------------ | ------- |
+| `CLASP_JSON`    | `development`     | `{"scriptId":"DEV_ID","projectId":"GCP_NUM","rootDir":"dist"}`     | Masked  |
+| `CLASP_JSON`    | `production`      | `{"scriptId":"PROD_ID","projectId":"GCP_NUM","rootDir":"dist"}`    | Masked  |
+| `DEPLOYMENT_ID` | `development`     | Your dev deployment ID                                             |         |
+| `DEPLOYMENT_ID` | `production`      | Your prod deployment ID                                            |         |
 
 ### 4. Set up Template Sync