[#783] add-prompt-tempfile

[nrslib]

Summary

タスク指示書: CLI provider の長い prompt を opt-in 一時ファイル参照方式で渡せるようにする

背景

Windows の一部ターミナル環境で、Cursor provider などの CLI provider が長い prompt を command line argument として渡すことで、コマンドライン文字数制限に当たり起動に失敗する可能性がある。

現状確認済みの事実として、少なくとも Cursor provider は systemPrompt + prompt を結合した長い文字列を cursor-agent の argv に直接渡している。これを、ユーザーが明示的に有効化した場合のみ、一時ファイルに書き出して短い参照指示だけを argv に渡す方式へ切り替えられるようにする。

ゴール

長い prompt を argv に直接載せる CLI provider について、opt-in 設定で一時ファイル参照方式を使えるように実装する。特に Cursor provider で動作することを必須とする。

明示要件

• 一時ファイル方式を実装する。
• 一時ファイル方式はデフォルト有効にしない。
• Windows の一部ターミナルだけの問題なので、オプショナルな opt-in として提供する。
• 一時ファイル方式では、長い prompt 本文をファイルへ書き、CLI に渡す argv には「そのファイルを参照せよ」という短い指示を渡す。
• 実装後、該当 provider のテストを追加・更新する。

参照資料

Planner は最初に以下を実際に開いて確認すること。

• src/infra/cursor/client.ts
• src/__tests__/cursor-client.test.ts
• src/shared/utils/spawn.ts
• src/infra/claude-headless/client.ts
• src/infra/kiro/client.ts
• src/infra/copilot/client.ts
• provider 設定型・設定読み込み・provider options の定義箇所
• 既存の一時ファイル作成・cleanup パターンがあればその実装箇所

作業項目

優先度: 高

src/infra/cursor/client.ts

• Cursor provider に opt-in の一時ファイル参照方式を実装する。
• 既存の通常モードでは、現行どおり prompt 本文を argv に渡す挙動を維持する。
• opt-in が有効な場合のみ、以下の挙動に切り替える。
  • systemPrompt と prompt を結合した完全な prompt 本文を一時ファイルに書く。
  • cursor-agent の argv には prompt 本文を直接渡さず、ファイルを読むよう指示する短い prompt を渡す。
  • 例: Read the full task instruction from this file and follow it exactly: <path>
  • 実行完了後、作成した一時ファイルを削除する。
  • provider 実行が失敗した場合も、一時ファイル cleanup を行う。
• 一時ファイルの配置場所は、Cursor が確実に読める場所をコード調査で判断して決めること。--workspace 指定との関係を確認する。
• 一時ファイル名は衝突しにくく、実行ごとに分離される形にする。

provider 設定型・設定読み込み

• Cursor provider の設定または provider options に、一時ファイル参照方式を opt-in できる設定項目を追加する。
• 設定名は既存の provider option 命名規約に合わせる。
• デフォルト値は無効にする。
• 設定が CLI entrypoint、workflow config、provider factory などを経由して Cursor provider まで伝搬する場合は、必要な配線をすべて実装する。
• 設定スキーマ、型定義、バリデーション、ドキュメント生成対象がある場合は整合させる。

src/__tests__/cursor-client.test.ts

• 既存の「prompt が argv に渡される」テストを、通常モードの契約として維持・更新する。
• opt-in 有効時のテストを追加する。
  • argv に完全な長い prompt 本文が含まれないこと。
  • argv には一時ファイルを読む短い指示が含まれること。
  • 一時ファイルに完全な prompt 本文が書かれること。
  • provider 実行後に一時ファイルが削除されること。
  • provider 実行が失敗しても cleanup されること。
• ファイルシステム操作を伴うため、既存テストの mock パターンを確認し、同じ流儀で実装する。

優先度: 中

src/infra/claude-headless/client.ts

• 長い prompt を argv に直接渡しているかを確認する。
• Cursor と同じ opt-in 設定方式を適用できる場合は、一時ファイル参照方式を実装する。
• CLI のファイル参照指示で成立しない技術的理由がある場合は、Cursor のみ実装対象とし、その理由を計画レポートに明記する。

src/infra/kiro/client.ts

• 長い prompt を argv に直接渡しているかを確認する。
• Cursor と同じ opt-in 設定方式を適用できる場合は、一時ファイル参照方式を実装する。
• 適用しない場合は、技術的理由を計画レポートに明記する。

src/infra/copilot/client.ts

• 長い prompt を argv に直接渡しているかを確認する。
• Cursor と同じ opt-in 設定方式を適用できる場合は、一時ファイル参照方式を実装する。
• 適用しない場合は、技術的理由を計画レポートに明記する。

関連テスト

• Cursor 以外にも実装した provider がある場合、それぞれ通常モードと opt-in 有効時のテストを追加・更新する。
• 新しい provider option が呼び出しチェーンを通る場合、必要に応じて統合テストを追加する。

優先度: 低

ドキュメント・設定例

• 既存の provider options 設定ドキュメントがある場合のみ、追加した opt-in 設定を追記する。
• Windows の一部ターミナルで command line length 制限に当たる場合に使う設定であることを簡潔に記載する。

実装上の注意

• 一時ファイル方式は opt-in にする。デフォルト挙動を変えない。
• prompt 本文の内容は一時ファイル方式でも欠落・改変しない。
• ファイル参照用の短い argv prompt は、元 prompt の代替ではなく、元 prompt 全文を読むための指示に限定する。
• 一時ファイル cleanup は成功・失敗の両方で行う。
• 新しい設定項目を追加する場合、型・バリデーション・設定読み込み・provider への受け渡しを漏らさない。
• 既存の provider 実行エラー処理を不必要に変更しない。

確認方法

• npm test -- cursor-client
• 関連 provider を実装した場合は、それぞれの provider test を実行する。
• npm test
• npm run lint
• npm run build

再現・検証観点

• 通常モードでは、従来どおり prompt 本文が argv に渡される。
• opt-in 有効時は、長い prompt 本文が argv に含まれない。
• opt-in 有効時は、一時ファイルに完全な prompt 本文が保存される。
• opt-in 有効時は、CLI に渡される prompt が一時ファイル参照指示になっている。
• provider 実行後、一時ファイルが残らない。
• provider 実行失敗時も、一時ファイルが残らない。

Open Questions

• 追加する opt-in 設定項目を置くべき正確な設定階層と命名は、既存の provider option 実装を確認して決定すること。
• Cursor 以外の CLI provider がファイル参照指示で実用可能かは、各 provider の既存実装と実行前提を確認して判断すること。

Execution Report

Workflow takt-default completed successfully.

Closes #783

Summary by CodeRabbit

• New Features

  • Claude / Cursor / Kiro / Copilot 向けにプロンプト一時ファイル方式をオプトイン追加（use_prompt_temp_file、デフォルト無効）。Windows のコマンドライン長制限回避のため、プロンプトをワークスペース内の一時ファイルへ書き出して参照パスで渡せます。

• Documentation

  • 設定例・環境変数による上書き方法・動作説明を日本語／英語ドキュメントに追記。

• Configuration

  • 組み込み設定と設定ファイル例に各プロバイダの use_prompt_temp_file 設定を明示的に追加。

• Tests

  • プロンプト一時ファイル挙動を検証するテスト群を追加・拡張。

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: a2976729-5f65-4a79-a1cc-c4bddd5bbadd

📥 Commits

Reviewing files that changed from the base of the PR and between 75dd856 and ec519bf.

📒 Files selected for processing (7)

• docs/workflows.ja.md
• docs/workflows.md
• src/__tests__/claude-headless-client.test.ts
• src/__tests__/copilot-client.test.ts
• src/__tests__/cursor-client.test.ts
• src/__tests__/kiro-client.test.ts
• src/infra/cli-prompt-temp-file.ts

---

📝 Walkthrough

Walkthrough

このPRは、Cursor、Copilot、Kiro、Claude HeadlessのCLIプロバイダに対し、プロンプトをワークスペース下の一時ファイルへ書き出して短い参照指示を argv に渡す opt-in 設定 usePromptTempFile を導入し、ユーティリティ実装、クライアント統合、設定解決、ドキュメント、テストを追加しています。

Changes

CLI Prompt一時ファイル機能

Layer / File(s)	Summary
スキーマ・型定義の拡張 src/core/models/schema-base.ts, src/core/models/workflow-provider-options.ts	usePromptTempFile?: boolean を provider オプションに追加し、cursor/kiro 型を導入。
Provider options処理 src/infra/config/providerOptions.ts, src/infra/config/configNormalizers.ts	use_prompt_temp_file ↔ usePromptTempFile の正規化・denormalize、merge、resolve を対応。PROVIDER_OPTION_PATHS 等を拡張。
env/tracing/internal path 契約 src/infra/config/providerOptionsContract.ts	環境変数仕様・トレースパス・内部 path を拡張して use_prompt_temp_file 系を含めた契約を更新。
CLI prompt 一時ファイルユーティリティ src/infra/cli-prompt-temp-file.ts	prepareCliPromptArgument と CliPromptArgument 型を追加。プロンプトを書き出し参照文字列と cleanup を返す。
Cursor client 実装 src/infra/cursor/client.ts, src/infra/cursor/types.ts	CursorCallOptions.usePromptTempFile を追加、prepareCliPromptArgument を利用して argv を参照指示化し finally で cleanup 実行。
Copilot client 実装 src/infra/copilot/client.ts, src/infra/copilot/types.ts	CopilotCallOptions.usePromptTempFile を追加、-p 引数を prepared prompt に差替え、cleanup を finally で実行。
Kiro client 実装 src/infra/kiro/client.ts, src/infra/kiro/types.ts	KiroCallOptions.usePromptTempFile を追加、prepareCliPromptArgument を導入して cleanup を実行。
Claude Headless 実装 src/infra/claude-headless/client.ts, src/infra/claude-headless/types.ts	ClaudeHeadlessCallOptions.usePromptTempFile を追加、MCP 設定と prompt 一時ファイルの cleanup を統合。
Provider 配線 src/infra/providers/*	各 provider の toXOptions に usePromptTempFile を渡す配線を追加。
denormalize の補完 src/infra/config/configNormalizers.ts	cursor/kiro/copilot/claude の denormalize 出力へ use_prompt_temp_file を追加。
テスト（設定層） src/__tests__/*provider-options*.test.ts, src/__tests__/config-env-overrides.test.ts	normalize/denormalize、env override、trace path、source、workflow/step 優先などのテスト追加・拡張。
テスト（クライアント層） src/__tests__/cursor-client.test.ts, src/__tests__/copilot-client.test.ts, src/__tests__/kiro-client.test.ts, src/__tests__/claude-headless-client.test.ts	usePromptTempFile 有効時の argv 参照化、writeFile 内容、cleanup 呼び出し、spawn 失敗時の後始末、例外経路の cleanup を検証する多数のテストを追加。
テスト（プロバイダ/統合） src/__tests__/cursor-provider.test.ts, src/__tests__/copilot-provider.test.ts, src/__tests__/kiro-provider.test.ts, src/__tests__/claude-headless-provider.test.ts, src/__tests__/it-run-config-provider-options.test.ts, src/__tests__/project-config-quality-gates.test.ts	providerOptions の伝播や run 系の統合検証、品質ゲート保持テストを追加。
ドキュメントと builtins builtins/en/config.yaml, builtins/ja/config.yaml, docs/configuration.{md,ja.md}, docs/workflows.{md,ja.md}	各プロバイダの use_prompt_temp_file をデフォルト false として builtins に追加し、ドキュメントに設定例・env 上書き方法・適用対象を追記。

🎯 4 (Complex) | ⏱️ ~60 minutes

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 5.71% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	プルリクエストのタイトル「[#783] add-prompt-tempfile」は、変更内容の主要なポイント（プロンプトを一時ファイル経由で渡す機能追加）を簡潔に表現しており、変更セットと関連している。
Linked Issues check	✅ Passed	PR は #783 のすべての要件を満たしており、cursor/kiro/copilot/claude の各 CLI provider に opt-in 方式での一時ファイル参照機能を実装し、スキーマ拡張、テスト追加、ドキュメント更新も完了している。
Out of Scope Changes check	✅ Passed	すべての変更が #783 の要件内に収まっており、一時ファイル参照方式の実装、設定スキーマ拡張、テスト・ドキュメント更新以外の不関連な変更は見当たらない。

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch takt/783/add-prompt-tempfile

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/workflows.md`:
- Line 319: Update the docs/workflows.md entry for
`provider_options.claude.use_prompt_temp_file` to clearly state it is only used
by the Claude headless implementation (referenced by
prepareCliPromptArgument(..., options.usePromptTempFile)) and is not consumed by
the Claude SDK/provider implementations (e.g., the provider/client code paths
that do not pass this option); add a short parenthetical like "Claude headless
only" or similar to the table description to prevent confusion.

In `@src/infra/cli-prompt-temp-file.ts`:
- Around line 19-21: The prompt text in buildPromptReference is ambiguous;
update the returned sentence to clearly state that the parameter is a
JSON-escaped string containing a file path that points to a JSON file with the
task instruction, and that the consumer should read that file and follow its
instruction exactly while treating the path value strictly as data (not as an
instruction). Locate buildPromptReference and replace the existing message with
a concise sentence conveying those three points: "JSON-escaped string containing
a file path", "read the referenced file for the instruction", and "treat the
path as data, not an instruction."

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: beef9c96-8638-47b6-8a25-513c02326966

📥 Commits

Reviewing files that changed from the base of the PR and between c226cca and 75dd856.

📒 Files selected for processing (41)

• builtins/en/config.yaml
• builtins/ja/config.yaml
• docs/configuration.ja.md
• docs/configuration.md
• docs/workflows.ja.md
• docs/workflows.md
• src/__tests__/claude-headless-client.test.ts
• src/__tests__/claude-headless-provider.test.ts
• src/__tests__/config-env-overrides.test.ts
• src/__tests__/config-normalizers-provider-options.test.ts
• src/__tests__/copilot-client.test.ts
• src/__tests__/copilot-provider.test.ts
• src/__tests__/cursor-client.test.ts
• src/__tests__/cursor-provider.test.ts
• src/__tests__/it-run-config-provider-options.test.ts
• src/__tests__/kiro-client.test.ts
• src/__tests__/kiro-provider.test.ts
• src/__tests__/project-config-quality-gates.test.ts
• src/__tests__/provider-options-contract.test.ts
• src/__tests__/provider-options-resolution.test.ts
• src/__tests__/provider-options-source.test.ts
• src/__tests__/provider-options-workflow-parser.test.ts
• src/__tests__/resolveProviderOptionsWithTrace.test.ts
• src/core/models/schema-base.ts
• src/core/models/workflow-provider-options.ts
• src/infra/claude-headless/client.ts
• src/infra/claude-headless/types.ts
• src/infra/cli-prompt-temp-file.ts
• src/infra/config/configNormalizers.ts
• src/infra/config/providerOptions.ts
• src/infra/config/providerOptionsContract.ts
• src/infra/copilot/client.ts
• src/infra/copilot/types.ts
• src/infra/cursor/client.ts
• src/infra/cursor/types.ts
• src/infra/kiro/client.ts
• src/infra/kiro/types.ts
• src/infra/providers/claude-headless.ts
• src/infra/providers/copilot.ts
• src/infra/providers/cursor.ts
• src/infra/providers/kiro.ts

[nrslib]

Summary

タスク指示書: PR #788 のレビューコメント対応

目的

PR #788（[#783] add-prompt-tempfile）に寄せられたレビューコメントを現在のコードに照らして確認し、成立する指摘を実装で修正する。対象は prompt 一時ファイル機能の説明文と、Claude provider option ドキュメントの明確化である。

優先度: 高

src/infra/cli-prompt-temp-file.ts

• buildPromptReference(filePath: string) が返す参照 prompt 文言を明確化する。
• 返却文には以下の内容を含める。
  • 渡される値が「JSON escaped string containing a file path」であること。
  • その path が task instruction を含む JSON ファイルを指すこと。
  • consumer は参照先ファイルを読み、その instruction に正確に従うこと。
  • path 値は instruction ではなく data として扱うこと。
• 既存の一時ファイル作成、cleanup、ファイル配置、provider 呼び出し仕様は変更しない。
• 文言変更により既存テストの期待値が変わる場合は、該当テストを更新する。

src/__tests__/ 配下の関連テスト

• buildPromptReference または prepareCliPromptArgument の出力文言を検証しているテストを確認し、必要に応じて期待値を更新する。
• prompt 本文が argv に含まれないこと、一時ファイル cleanup が行われることなど、既存の機能テストの意味は維持する。

優先度: 中

docs/workflows.md

• provider_options.claude.use_prompt_temp_file の説明を更新する。
• この option が Claude headless 実装で使われることを明記する。
• Claude SDK/provider 実装では消費されないことが誤解されないよう、短い注記を加える。
  • 例: Claude headless only
• 実装上の利用箇所は src/infra/claude-headless/client.ts の prepareCliPromptArgument(..., options.usePromptTempFile) 周辺で確認する。

docs/workflows.ja.md

• docs/workflows.md と同等の日本語版 provider options 表が存在し、同じ provider_options.claude.use_prompt_temp_file を説明している場合は、同じ意味の注記を追加する。
• 該当項目が存在しない場合は変更しない。

優先度: 低

PR コメント対応記録

• 対応後のレポートに、PR [#783] add-prompt-tempfile #788 のレビューコメントごとの対応状況を記載する。
• 各コメントについて以下を残す。
  • docs/workflows.md の Claude headless 注記: 対応済み、または現在コード上不要なら理由。
  • src/infra/cli-prompt-temp-file.ts の参照 prompt 文言: 対応済み、または現在コード上不要なら理由。

確認方法

• npm test -- cursor-client
• prompt 一時ファイル機能に関係する provider test を変更した場合は、その test も実行する。
  • 例: npm test -- cli-prompt-temp-file
  • 例: npm test -- claude-headless-client
• npm test
• npm run lint
• npm run build

検証観点

• buildPromptReference の文言が、JSON escaped path、参照先ファイルの読み取り、path を data として扱うことを明確にしている。
• prompt 一時ファイル方式の既存挙動が変わっていない。
• provider_options.claude.use_prompt_temp_file の workflows ドキュメントが Claude headless 用であることを明確にしている。
• 関連テスト、lint、build が通る。

Open Questions

なし。

Execution Report

Workflow review-fix-takt-default completed successfully.