Designing Agent Context by Scope and Time

📝 摘要

本文提出了一种按 作用范围（Scope）和进入时机（Time） 来设计智能体上下文的系统化框架。当智能体表现不佳时，常见做法是扩大系统提示或增加新智能体，但更关键的设计问题是：智能体缺失了什么信息或控制，以及这些内容应在何时、以何种范围进入运行？ 文章将智能体系统归纳为 7 种上下文/控制注入机制，并逐一分析其入口时机、作用范围和核心权衡。

核心概念： 智能体上下文设计的本质不是"更多上下文"，而是"正确放置的上下文"——用最窄的机制在信息变得相关的时刻引入所需内容。

关键技术栈 / 关键要点：

User Prompt — 运行时随当前轮次追加，精确灵活但依赖用户记忆重复指令
System Prompt — 稳定前缀每调用可见，全运行一致但消耗上下文且易冲突
Scoped Instructions（CLAUDE.md / 路径规则） — 按位置激活的引导，API 约定跟着 API 代码走，去除无关上下文
Skills — 按选择加载的可复用程序，渐进式披露节省上下文但引入路由风险
Tools — 定义影响模型能力认知，调用结果影响模型世界认知，MCP 提供连接
Steering（权限 / Hooks） — 运行中干预，区分模型应做什么与运行时允许做什么
Delegation — 开启独立上下文，隔离中间工作但代价是成本、延迟和有损交接

关键结论 / 实践建议： 当智能体陷入困境时，问三个问题：(1) 缺失的信息/控制应在何时进入？(2) 它应覆盖多远？(3) 工作是否需要独立上下文？选择能将缺失内容在相关时刻引入的最窄机制。

When an agent performs poorly, we often blame the model.

Then we enlarge the system prompt. When that becomes unwieldy, we add another agent.

Both can help, but they skip a more useful design question:

What is the agent missing, and where should that information or control enter the run?

Agent systems have seven common ways to add context or control:

User prompts
System prompts
Scoped instructions
Skills
Tools
Steering
Delegation

They differ in when they enter, how far they reach, how long they remain, and whether the work stays in the current context.

I use Claude Code for the examples, but the patterns apply across agent frameworks.

查看图片描述

ALT

The diagrams track two clocks. The left side shows when the runtime resolves a source. The right side shows model input over successive calls.

Some context forms a stable prefix that is presented on every call and may be cached. Other context joins growing history and may later be compacted.

Configured once does not mean seen once.

1. User prompt: what matters now

查看图片描述

ALT

Source: User message, referenced file, or attachment Entry point: Appended with the current turn Scope: Current task and later history until cleared or compacted Main trade-off: Precise and flexible, but recurring guidance depends on the user remembering it

The user prompt enters at runtime with the current turn. Attachments and referenced files can arrive with it. Once appended, the request may remain available to later calls even though its intended scope is the current task.

plaintext

> Review @docs/chapter.md.
> Focus on the argument and examples.
> Do not rewrite it yet.

Use it for one-off objectives, corrections, output requirements, and material relevant to this task.

If the same instruction applies to nearly every task, it probably belongs in the system prompt.

2. System prompt: the standing baseline

查看图片描述

ALT

Source: Host configuration and built-in agent instructions Entry point: Stable prefix presented on every model call Scope: The whole run Main trade-off: Consistently available, but consumes context on every call and is increasingly prone to conflicts

The host configures the system prompt before the conversation starts. It defines identity, broad operating rules, universal constraints, and tool-use guidance.

bash

claude --append-system-prompt \
  "Separate verified facts from inference."

Because that prefix reaches every call, reserve it for guidance that is truly universal. Repository conventions need a narrower scope.

3. Scoped instructions: guidance that follows the work

查看图片描述

ALT

Source: CLAUDE.md, imported AGENTS.md, nested files, and path rules Entry point: At startup or when a matching location becomes relevant Scope: Repository, directory, or file pattern Main trade-off: Removes irrelevant context, but makes active instructions less visible and remains advisory

Root instructions can load at startup. Nested files or path rules can enter when the agent reads a matching part of the repository. API conventions stay with API code, rather than making every unrelated task carry them. Use pnpm, not npm.

markdown

# CLAUDE.md

@AGENTS.md
Use pnpm, not npm.

Validate every public API input.

markdown

---
paths: ["src/api/**/*.ts"]
---
Validate every public API input.

These files guide the model. They do not guarantee compliance. Runtime permissions and hooks provide stronger control.

Location can decide where guidance applies. A reusable procedure needs a different trigger.

4. Skills: procedures loaded after selection

查看图片描述

ALT

Source: Skill metadata and SKILL.md Entry point: Metadata for discovery first, full instructions on selection Scope: A recurring procedure used for the current task Main trade-off: Progressive disclosure saves context, but introduces routing risk

A Skill packages instructions for a recurring task. The agent can first see only its name and description. When selected, the full procedure enters working context. References, assets, and scripts can remain outside until needed.

markdown

---
name: release-check
description: Verify production release readiness.
---

1. Run the required tests.
2. Check migrations and rollback readiness.
3. Return a go or no-go decision with evidence.

A scoped instruction is activated by location. A Skill is activated because a procedure was selected.

A Skill explains how to work. It does not provide access to live systems.

5. Tools: capabilities in, results back

查看图片描述

ALT

Source: Configured tool definition, including tools exposed through MCP Entry point: Name, description, and schema before inference; result after invocation Scope: Capability catalog plus the individual call result Main trade-off: Enables live data and action, but adds context, permissions, latency, failures, and side effects

Tools affect context twice. Before inference, the name, description, and input schema tell the model what it can do. After invocation, the result joins the conversation.

json

{
  "name": "release_status",
  "description": "Read deployment state for a service.",
  "input_schema": {
    "type": "object",
    "properties": {
      "service": { "type": "string" }
    },
    "required": ["service"]
  }
}

The definition changes what the model knows it can do. The result changes what it knows about the world.

MCP can supply the connection. A Skill can explain when to check a deployment, while a tool retrieves its actual state.

Access to an action still does not mean the action should run automatically.

6. Steering: intervene during execution

查看图片描述

ALT

Source: Human input, permission rule, hook, or runtime policy Entry point: At a live decision, as a gate or guidance for the next call Scope: The current action or model step Main trade-off: Strong runtime control, but more branches, retries, latency, and testing

Steering acts while the loop is running. A human or hook can inject corrective guidance into the next call. A permission policy can gate a proposed action without adding anything to model context.

json

{
  "permissions": {
    "ask": ["Bash(git push *)"],
    "deny": ["Read(./secrets/**)"]
  }
}

This is the difference between what the model should do and what the runtime will allow.

A passive hook is instrumentation. It becomes steering when it can inject, rewrite, approve, pause, or block.

Sometimes the current loop still is not the right place for the work.

7. Delegation: open a separate context

查看图片描述

ALT

Source: Parent task plus the worker's own instructions and selected inputs Entry point: Usually into a separate worker context; bounded result returns to the parent Scope: A separate agent loop Main trade-off: Context isolation and parallelism versus cost, latency, lossy handoffs, and file collisions

Delegation hands a bounded task and selected context to another agent loop. Typically, the worker gets its own instructions, tools, and history, performs the detailed work separately, then returns a bounded result to the parent.

plaintext

> Run the security-reviewer and test-runner in parallel.
> Give each the changed files, then combine their findings.

Independent workers can also run concurrently. Context isolation keeps their intermediate work out of the parent window.

Context isolation is not filesystem isolation. Parallel edits may still need worktrees, sandboxes, or explicit file ownership.

Choose by scope and time

When an agent struggles, ask three questions:

When should the missing information or control enter?
How far should it reach?
Does the work need a separate context?

查看图片描述

ALT

Use the narrowest mechanism that introduces what is missing where it becomes relevant.

The goal is not more context. It is correctly placed context.

Read the full article for the implementation details, framework references, and edge cases:

https://generativeprogrammer.com/p/designing-agent-context-by-scope

📝 摘要 #

1. User prompt: what matters now #

2. System prompt: the standing baseline #

3. Scoped instructions: guidance that follows the work #

4. Skills: procedures loaded after selection #

5. Tools: capabilities in, results back #

6. Steering: intervene during execution #

7. Delegation: open a separate context #

Choose by scope and time #

📝 摘要

1. User prompt: what matters now

2. System prompt: the standing baseline

3. Scoped instructions: guidance that follows the work

4. Skills: procedures loaded after selection

5. Tools: capabilities in, results back

6. Steering: intervene during execution

7. Delegation: open a separate context

Choose by scope and time