6 ファイル変更 +641 -137
この更新の概要
Agent SDKにおいて、ユーザーやマシン間でプロンプトキャッシュを効率的に共有するためのexcludeDynamicSectionsオプションが追加されました。Windowsユーザー向けのクイックスタートガイドには、PowerShellとCMDを切り替える新しいUIコンポーネントが導入されています。Web版のClaude Codeでは、URLクエリパラメータを使用してプロンプトやリポジトリ、環境設定を事前入力できる機能が公開されました。全体として、キャッシュ効率の向上と導入プロセスのユーザー体験改善に重点が置かれています。
ディレクトリやOS情報などの動的なコンテキストをシステムプロンプトから除外することで、キャッシュのヒット率を高めるexcludeDynamicSectionsオプションの仕組みとトレードオフを解説しています。
@@ -274,6 +274,55 @@ async for message in query(
print(message.message.content)
```
#### Improve prompt caching across users and machines
By default, two sessions that use the same `claude_code` preset and `append` text still cannot share a prompt cache entry if they run from different working directories. This is because the preset embeds per-session context in the system prompt ahead of your `append` text: the working directory, platform and OS version, current date, git status, and auto-memory paths. Any difference in that context produces a different system prompt and a cache miss.
To make the system prompt identical across sessions, set `excludeDynamicSections: true` in TypeScript or `"exclude_dynamic_sections": True` in Python. The per-session context moves into the first user message, leaving only the static preset and your `append` text in the system prompt so identical configurations share a cache entry across users and machines.
`excludeDynamicSections` requires `@anthropic-ai/claude-agent-sdk` v0.2.98 or later, or `claude-agent-sdk` v0.1.58 or later for Python. It applies only to the preset object form and has no effect when `systemPrompt` is a string.
The following example pairs a shared `append` block with `excludeDynamicSections` so a fleet of agents running from different directories can reuse the same cached system prompt:
```typescript TypeScript theme={null}
import { query } from "@anthropic-ai/claude-agent-sdk";
for await (const message of query({
prompt: "Triage the open issues in this repo",
options: {
systemPrompt: {
type: "preset",
preset: "claude_code",
append: "You operate Acme's internal triage workflow. Label issues by component and severity.",
excludeDynamicSections: true
}
}
})) {
// ...
}
```
```python Python theme={null}
from claude_agent_sdk import query, ClaudeAgentOptions
async for message in query(
prompt="Triage the open issues in this repo",
options=ClaudeAgentOptions(
system_prompt={
"type": "preset",
"preset": "claude_code",
"append": "You operate Acme's internal triage workflow. Label issues by component and severity.",
"exclude_dynamic_sections": True,
},
),
):
...
```
**Tradeoffs:** the working directory, git status, and memory location still reach Claude, but as part of the first user message rather than the system prompt. Instructions in the user message carry marginally less weight than the same text in the system prompt, so Claude may rely on them less strongly when reasoning about the current directory or auto-memory paths. Enable this option when cross-session cache reuse matters more than maximally authoritative environment context.
For the equivalent flag in non-interactive CLI mode, see [`--exclude-dynamic-system-prompt-sections`](/en/cli-reference).
### Method 4: Custom system prompts
You can provide a custom string as `systemPrompt` to replace the default entirely with your own instructions.
Python版SDKのオプション定義にexclude_dynamic_sectionsを追加し、プロンプトキャッシュの再利用性を向上させる設定項目を追記しています。
@@ -835,6 +835,7 @@ class SystemPromptPreset(TypedDict):
type: Literal["preset"]
preset: Literal["claude_code"]
append: NotRequired[str]
exclude_dynamic_sections: NotRequired[bool]
```
| Field | Required | Description |
@@ -842,6 +843,7 @@ class SystemPromptPreset(TypedDict):
| `type` | Yes | Must be `"preset"` to use a preset system prompt |
| `preset` | Yes | Must be `"claude_code"` to use Claude Code's system prompt |
| `append` | No | Additional instructions to append to the preset system prompt |
| `exclude_dynamic_sections` | No | Move per-session context such as working directory, git status, and memory paths from the system prompt into the first user message. Improves prompt-cache reuse across users and machines. See [Modify system prompts](/en/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines) |
### `SettingSource`
TypeScript版SDKのsystemPrompt型定義を更新し、セッション固有の情報をユーザーメッセージに移動させるための新しいプロパティを追加しています。
@@ -318,7 +318,7 @@ Configuration object for the `query()` function.
| `spawnClaudeCodeProcess` | `(options: SpawnOptions) => SpawnedProcess` | `undefined` | Custom function to spawn the Claude Code process. Use to run Claude Code in VMs, containers, or remote environments |
| `stderr` | `(data: string) => void` | `undefined` | Callback for stderr output |
| `strictMcpConfig` | `boolean` | `false` | Enforce strict MCP validation |
| `systemPrompt` | `string \| { type: 'preset'; preset: 'claude_code'; append?: string }` | `undefined` (minimal prompt) | System prompt configuration. Pass a string for custom prompt, or `{ type: 'preset', preset: 'claude_code' }` to use Claude Code's system prompt. When using the preset object form, add `append` to extend the system prompt with additional instructions |
| `systemPrompt` | `string \| { type: 'preset'; preset: 'claude_code'; append?: string; excludeDynamicSections?: boolean }` | `undefined` (minimal prompt) | System prompt configuration. Pass a string for custom prompt, or `{ type: 'preset', preset: 'claude_code' }` to use Claude Code's system prompt. When using the preset object form, add `append` to extend it with additional instructions, and set `excludeDynamicSections: true` to move per-session context into the first user message for [better prompt-cache reuse across machines](/en/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines) |
| `thinking` | [`ThinkingConfig`](#thinking-config) | `{ type: 'adaptive' }` for supported models | Controls Claude's thinking/reasoning behavior. See [`ThinkingConfig`](#thinking-config) for options |
| `toolConfig` | [`ToolConfig`](#tool-config) | `undefined` | Configuration for built-in tool behavior. See [`ToolConfig`](#tool-config) for details |
| `tools` | `string[] \| { type: 'preset'; preset: 'claude_code' }` | `undefined` | Tool configuration. Pass an array of tool names or use the preset to get Claude Code's default tools |
@@ -134,7 +134,6 @@ source: https://code.claude.com/docs/en/quickstart.md
border-bottom: 0.5px solid rgba(255, 255, 255, 0.08);
padding: 0 8px; overflow-x: auto;
}
.cc-ic-subtab-spacer { flex: 1; }
.cc-ic-subtab {
appearance: none; background: none; border: none;
padding: 12px 16px; font-size: 12px;
@@ -148,23 +147,28 @@ source: https://code.claude.com/docs/en/quickstart.md
left: 12px; right: 12px; bottom: -0.5px;
height: 2px; background: var(--ic-clay);
}
.cc-ic-cmd-toggle {
display: flex; align-items: center; gap: 8px; font-family: inherit;
background: none; border: none;
padding: 0 12px; font-size: 11px;
color: rgba(255, 255, 255, 0.5);
.cc-ic-shell-switch {
display: inline-flex; gap: 2px;
margin: 14px 26px 0; padding: 3px;
background: rgba(255, 255, 255, 0.06);
border: 0.5px solid rgba(255, 255, 255, 0.08);
border-radius: 8px;
font-family: inherit;
}
.cc-ic-shell-option {
font: inherit; font-size: 12px; font-weight: 500;
padding: 5px 12px; border-radius: 6px;
background: transparent; border: none;
color: rgba(255, 255, 255, 0.55);
cursor: pointer; user-select: none; white-space: nowrap;
transition: color 120ms ease, background-color 120ms ease;
}
.cc-ic-cmd-toggle:hover { color: rgba(255, 255, 255, 0.75); }
.cc-ic-mini-check {
width: 12px; height: 12px;
border: 1px solid rgba(255, 255, 255, 0.3); border-radius: 3px;
display: flex; align-items: center; justify-content: center;
flex-shrink: 0;
.cc-ic-shell-option:hover { color: rgba(255, 255, 255, 0.85); }
.cc-ic-shell-option.cc-ic-active {
background: rgba(255, 255, 255, 0.12);
color: #fff;
box-shadow: 0 1px 2px rgba(0, 0, 0, 0.25);
}
.cc-ic-mini-check svg { color: #fff; display: none; }
.cc-ic-cmd-toggle.cc-ic-checked .cc-ic-mini-check { background: var(--ic-clay-deep); border-color: var(--ic-clay-deep); }
.cc-ic-cmd-toggle.cc-ic-checked .cc-ic-mini-check svg { display: block; }
.cc-ic-card-body { padding: 24px 26px; display: flex; align-items: flex-start; gap: 14px; }
.cc-ic-prompt {
@@ -194,16 +198,24 @@ source: https://code.claude.com/docs/en/quickstart.md
.cc-ic-below a { color: var(--ic-gray-700); border-bottom: 0.5px solid var(--ic-border-default); }
.cc-ic-below a:hover { color: var(--ic-clay-deep); border-bottom-color: var(--ic-clay-deep); }
.cc-ic-handoff {
padding: 20px 22px;
background: var(--ic-gray-000);
padding: 22px 24px;
background: linear-gradient(180deg, #faf9f4 0%, #f3f1e9 100%);
border: 0.5px solid var(--ic-border-default);
border-radius: 12px;
box-shadow: 0 1px 2px rgba(31, 30, 29, 0.04), 0 6px 16px -4px rgba(31, 30, 29, 0.06);
}
.dark .cc-ic-handoff {
background: linear-gradient(180deg, #262624 0%, #1f1e1d 100%);
box-shadow: 0 1px 2px rgba(0, 0, 0, 0.3), 0 6px 16px -4px rgba(0, 0, 0, 0.4);
}
.cc-ic-handoff-title {
font-size: 16px; font-weight: 550; color: var(--ic-slate);
letter-spacing: -0.01em; margin-bottom: 4px;
}
.cc-ic-handoff-head {
font-size: 14px; line-height: 1.55; color: var(--ic-gray-700);
margin-bottom: 14px;
.cc-ic-handoff-sub {
font-size: 14px; line-height: 1.5; color: var(--ic-gray-700);
margin-bottom: 18px;
}
.cc-ic-handoff-head strong { font-weight: 550; color: var(--ic-slate); }
.cc-ic-handoff-actions { display: flex; gap: 10px; flex-wrap: wrap; }
.cc-ic-handoff-alt {
margin-top: 12px; font-size: 12px; color: var(--ic-gray-550);
@@ -291,12 +303,21 @@ source: https://code.claude.com/docs/en/quickstart.md
{Object.keys(TERM).map(k => <button key={k} type="button" role="tab" aria-selected={pkg === k} className={'cc-ic-subtab' + (pkg === k ? ' cc-ic-active' : '')} onClick={() => setPkg(k)}>
{TERM[k].label}
</button>)}
<span className="cc-ic-subtab-spacer" />
{isWinInstaller && <button type="button" role="switch" aria-checked={winCmd} className={'cc-ic-cmd-toggle' + (winCmd ? ' cc-ic-checked' : '')} onClick={() => setWinCmd(!winCmd)}>
<span className="cc-ic-mini-check">{iconCheck(9)}</span>
<span>CMD instead of PowerShell</span>
</button>}
</div>
{isWinInstaller && <div className="cc-ic-shell-switch" role="tablist" aria-label="Shell">
{[{
k: 'ps',
label: 'PowerShell'
}, {
k: 'cmd',
label: 'CMD'
}].map(({k, label}) => {
const active = k === 'cmd' === winCmd;
return <button key={k} type="button" role="tab" aria-selected={active} className={'cc-ic-shell-option' + (active ? ' cc-ic-active' : '')} onClick={() => setWinCmd(k === 'cmd')}>
{label}
</button>;
})}
</div>}
{cardBodyCmd(terminalCmd, isWinPrompt ? '>' : '$')}
</div>}
@@ -317,10 +338,8 @@ source: https://code.claude.com/docs/en/quickstart.md
</div>}
{alt && <div className="cc-ic-handoff">
<div className="cc-ic-handoff-head">
<strong>The steps below use the command line.</strong>{' '}
Prefer {alt.name}? Install here, then follow the {alt.name} guide instead.
</div>
<div className="cc-ic-handoff-title">Claude Code for {alt.name}</div>
<div className="cc-ic-handoff-sub">{alt.tagline}</div>
<div className="cc-ic-handoff-actions">
<a href={alt.installHref} className="cc-ic-btn-clay" {...alt.installHref.startsWith('http') ? {
target: '_blank',
@@ -344,7 +363,11 @@ source: https://code.claude.com/docs/en/quickstart.md
This quickstart guide will have you using AI-powered coding assistance in a few minutes. By the end, you'll understand how to use Claude Code for common development tasks.
<Experiment flag="quickstart-install-configurator" treatment={<InstallConfigurator />} />
<div className="install-configurator-slot">
<Experiment flag="install-configurator-default-surface" treatment={<InstallConfigurator defaultSurface="desktop" />}>
<InstallConfigurator />
</Experiment>
</div>
## Before you begin
claude.ai/codeのURLに引数を渡すことで、プロンプトやリポジトリをあらかじめ設定した状態でセッションを開始できるクエリパラメータの仕様を追加しています。
@@ -106,6 +106,23 @@ Type a description of what you want and press Enter. Be specific:
Claude clones the repositories, runs your setup script if configured, and starts working. Each task gets its own session and its own branch, so you don't need to wait for one to finish before starting another.
## Pre-fill sessions
You can prefill the prompt, repositories, and environment for a new session by adding query parameters to the [claude.ai/code](https://claude.ai/code) URL. Use this to build integrations such as a button in your issue tracker that opens Claude Code with the issue description as the prompt.
| Parameter | Description |
| :- | :- |
| `prompt` | Prompt text to prefill in the input box. The alias `q` is also accepted. |
| `prompt_url` | URL to fetch the prompt text from, for prompts too long to embed in a query string. The URL must allow cross-origin requests. Ignored when `prompt` is also set. |
| `repositories` | Comma-separated list of `owner/repo` slugs to preselect. The alias `repo` is also accepted. |
| `environment` | Name or ID of the [environment](#connect-github-and-create-an-environment) to preselect. |
URL-encode each value. The example below opens the form with a prompt and a repository already selected:
```text
https://claude.ai/code?prompt=Fix%20the%20login%20bug&repositories=acme/webapp
```
## Review and iterate
When Claude finishes, review the changes, leave feedback on specific lines, and keep going until the diff looks right.