From 8c49ddc99091ba78e5a53201df671376944c661d Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 20 Jun 2026 22:45:03 +0000 Subject: [PATCH 01/23] Add Claude guidance page Add a "Claude" page (docs/agents/) covering task selection, tool and model choice, context management, prompting, sycophancy, and security/responsibility for Claude tools in general, with Claude Code specifics where relevant. Link to official Anthropic documentation throughout. Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_0125gpj95EzqfeMYBMWscJae --- docs/agents/index.rst | 115 ++++++++++++++++++++++++++++++++++++++++++ docs/index.rst | 1 + 2 files changed, 116 insertions(+) create mode 100644 docs/agents/index.rst diff --git a/docs/agents/index.rst b/docs/agents/index.rst new file mode 100644 index 0000000..bb62c47 --- /dev/null +++ b/docs/agents/index.rst @@ -0,0 +1,115 @@ +Claude +====== + +.. seealso:: + + - Anthropic's `Claude Code best practices `__ + - Anthropic's `prompting best practices `__ + +This page explains how to get good results from Claude — both the chat apps and `Claude Code `__ — and how to use it responsibly on OCP's work. These tools change quickly, so treat specific commands and model names as correct at the time of writing, and check the linked official documentation for current details. + +If you had a poor experience with these tools, attend office hours before concluding that they don't work for your task: a small change in how you use them often makes the difference. + +Task selection +-------------- + +Claude is most useful on tasks where it can *use tools* — read your files, run commands, search the codebase, and check its own work — rather than answering from memory as a pure language model. Anthropic invests heavily in this tooling, and the results are noticeably better when Claude can act and verify than when it only predicts text. You can tell which mode it is in from the interface: a chat that only writes prose is acting as a language model, whereas a session that reads files, runs commands, and reports what it found is using tools. + +Prefer Claude for tasks that have a way to verify the result — a test suite, a build, a screenshot to compare, a script whose output you can check. Give it that check up front, and it can iterate to a working answer instead of stopping at the first plausible one. Reference: `Give Claude a way to verify its work `__. + +Tools +----- + +Match the tool to the task: + +- **Claude apps** (web, desktop, mobile) for chat: questions, drafting, and exploration that don't touch a repository. +- **Claude Code** for work in a codebase: reading, editing, running, and committing code. This is the surface most of OCP's development guidance below assumes. +- **The Claude browser extension** to act inside your live browser session (for example, a Google Doc). + + .. warning:: + + A browser extension operates with *your* live, authenticated session. Treat anything it can reach — email, internal documents, admin consoles — as in scope, and do not point it at confidential or production systems. + +.. note:: + + Anthropic ships several other surfaces (design, document, and collaborative-agent features) that evolve quickly. Confirm the current name and capabilities of any surface against the `official documentation `__ before relying on it. + +Models +------ + +Use the most capable model available to you, and the most thorough reasoning setting for demanding work. + +- In the **Claude apps**, select the strongest model in the model picker rather than leaving the default. +- In **Claude Code**, the ``best`` alias resolves to the most capable model your organization can access; otherwise choose it explicitly with ``/model``. For demanding work, raise the reasoning effort to its highest level with ``/effort`` (for example, ``xhigh`` on current Opus and Fable models). Reference: `Model configuration `__. + +More capable models and higher effort cost more and run slower, so drop to a simpler model or lower effort for routine, low-stakes tasks. + +Context +------- + +A language model has no memory of its own. Each time you send a message, the model re-reads the **entire** conversation so far — every message, every file it has opened, and every command's output. That transcript is bounded by a fixed **context window**, and model performance *degrades as the window fills*: Claude starts to "forget" earlier instructions and make more mistakes. Aim for a high-quality, focused context; a shorter context generally yields better results. Reference: `How Claude Code works `__. + +When a Claude Code session approaches the limit, it **compacts** the context — summarizing older turns to free space — which can lose detail. To work with this rather than against it: + +- See what is using the window with ``/context``, and compact deliberately with ``/compact`` (optionally ``/compact focus on the API changes``) instead of waiting for automatic compaction. +- Start a fresh conversation (``/clear``) between unrelated tasks. The trade-off is that Claude "forgets" everything; carry forward only what matters. +- Roll back to an earlier, cleaner point with ``/rewind`` (or press ``Esc`` twice) instead of correcting the same mistake repeatedly. +- For a quick aside that shouldn't bloat the transcript, use ``/btw``. + +Persist context *across* sessions so that clearing or starting fresh is cheap: + +- A ``CLAUDE.md`` file (generate a starting point with ``/init``) gives every session the same project context. **Skills** load task-specific instructions on demand. These are, in effect, a boilerplate first prompt that is always present — though the harness gives them somewhat higher priority than text you paste in. Keep them short: an over-long ``CLAUDE.md`` or a pile of uploaded documents *adds* noise and reduces adherence. Reference: `Memory `__. +- **Projects** are a feature of the Claude *apps*, not Claude Code; they retain instructions and uploaded files across chats. Claude Code's equivalent is ``CLAUDE.md`` plus skills. + +Two further effects on context: + +- "Thinking" reasoning consumes context, because the model generates reasoning that it then re-reads before answering. Use simpler models or lower effort for simpler tasks. +- Non-English text reportedly uses more tokens than English for the same content, so it fills the window faster. + +Prompting +--------- + +Provide as much *relevant* detail as is practical up front. A complete first prompt avoids a long back-and-forth that fills the context with corrections and changes of direction, which tends to confuse the model and lower the quality of its output. + +That said, do not over-engineer your prompts. You do not need to craft precise, elaborate instructions, pile on memories and skills, or apply "advanced" techniques from self-styled experts: the products already do a great deal of work behind the scenes — system prompts and tooling that Anthropic iterates on continually — and Anthropic's `prompt improver and generator `__ can refine a draft for you. With experience, you will learn which details matter and which you can leave out. + +A few habits that reliably help: + +- Give **example outputs** to follow. Claude is not an oracle; showing the shape of a good answer works better than describing it. +- If you don't yet know what you're asking for, use one session to refine the idea, then ask Claude to write a clean prompt for a fresh conversation. + +Sycophancy +---------- + +Be wary of sycophancy. Generative models are trained to be agreeable and positive, and there is no reliable way to turn this off. Do not read Claude's enthusiasm as validation of your idea or its own output. When you need a genuine critique, ask for it explicitly, or have a *fresh* session review the work — a separate context that didn't produce the work evaluates it more honestly than the one that did. + +Security and responsibility +--------------------------- + +Risks +~~~~~ + +The main risks are autonomous operation, over-broad permissions, and exposure of secrets or confidential data — for example, a shell command can read your SSH keys, and a debugging session can pull sensitive values into logs. A subtler, longer-term risk is skill atrophy from delegating work you no longer practice. + +Mitigations +~~~~~~~~~~~ + +Existing OCP practice already covers much of this: secrets are centralized, and ``bypassPermissions`` mode (formerly "dangerously skip permissions") is disabled. Beyond that: + +- **Limit permissions.** Keep approval prompts on, and add ``permissions.deny`` rules for sensitive paths — at minimum ``pillar/private`` and ``salt/private``. Remember that the Bash tool can read files such as ``~/.ssh``, so deny what Claude should never see. Reference: `Permissions `__. +- **Never give agents access to production.** +- **Don't leak through logs.** If you use Claude to debug logs, ensure those logs don't contain security, privacy, or confidential details. They shouldn't already — the same standard you apply to data sent to Sentry. + +Responsibility +~~~~~~~~~~~~~~ + +.. attention:: + + You are responsible for code you submit, whether or not Claude wrote it. + +Disclose unreviewed AI-generated code — for example, with a ``__generated_by__`` tag or a commit trailer — so reviewers and maintainers know what has and hasn't been checked. It is reasonable to skip thorough review only for low-stakes code: a proof of concept, a prototype, a one-time script, or a non-critical code path. Review anything that reaches a critical path. + +Administration +~~~~~~~~~~~~~~ + +Administrators manage Claude's GitHub access from the `Claude Code admin settings `__ and can enforce organization-wide policy (including disabling ``bypassPermissions`` mode) through managed settings. Reference: `Managed settings `__. diff --git a/docs/index.rst b/docs/index.rst index 26e9210..6dcbc43 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -23,6 +23,7 @@ This work is licensed under a `Creative Commons Attribution 4.0 International Li services/index git/index github/index + agents/index roadmap/index learning/index contributing From 1a6815313359b10c3aacc83b6dd10a2c3e1229b7 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 20 Jun 2026 22:56:25 +0000 Subject: [PATCH 02/23] Name Claude tool surfaces (Cowork, Microsoft 365, Design) Replace the placeholder note with verified product surfaces and official links: Claude Cowork (desktop), Claude for Microsoft 365 (Word/Excel/ PowerPoint/Outlook), and Claude Design. Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_0125gpj95EzqfeMYBMWscJae --- docs/agents/index.rst | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/agents/index.rst b/docs/agents/index.rst index bb62c47..d4329b5 100644 --- a/docs/agents/index.rst +++ b/docs/agents/index.rst @@ -23,7 +23,10 @@ Tools Match the tool to the task: - **Claude apps** (web, desktop, mobile) for chat: questions, drafting, and exploration that don't touch a repository. +- `Claude Cowork `__, in the desktop app, for multi-step knowledge work over your local files and folders — especially working on or searching through long documents. It uses the same agentic approach as Claude Code, without the terminal. - **Claude Code** for work in a codebase: reading, editing, running, and committing code. This is the surface most of OCP's development guidance below assumes. +- `Claude for Microsoft 365 `__: add-ins that bring Claude into Word, Excel, PowerPoint, and Outlook, sharing context across your open documents. +- `Claude Design `__ for visual work: designs, prototypes, slides, and one-pagers. - **The Claude browser extension** to act inside your live browser session (for example, a Google Doc). .. warning:: @@ -32,7 +35,7 @@ Match the tool to the task: .. note:: - Anthropic ships several other surfaces (design, document, and collaborative-agent features) that evolve quickly. Confirm the current name and capabilities of any surface against the `official documentation `__ before relying on it. + These surfaces evolve quickly, and some are in research preview. Confirm the current name, availability, and capabilities of any surface against the `official documentation `__ before relying on it. Models ------ From 5e2475e096966e44dfa178e2c4a6eca0876c4e5b Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 20 Jun 2026 23:16:29 +0000 Subject: [PATCH 03/23] Make Context section surface-neutral for non-coders Generalize the context-window and compaction explanation across all Claude products (auto-compaction happens in the chat apps too), and cordon the Claude Code commands into a clearly labeled subsection that non-developer readers can skip. Present Projects (apps) and CLAUDE.md/Skills (Claude Code) side by side for persisting context across conversations. Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_0125gpj95EzqfeMYBMWscJae --- docs/agents/index.rst | 24 +++++++++++++++++------- 1 file changed, 17 insertions(+), 7 deletions(-) diff --git a/docs/agents/index.rst b/docs/agents/index.rst index d4329b5..fb389e3 100644 --- a/docs/agents/index.rst +++ b/docs/agents/index.rst @@ -50,21 +50,31 @@ More capable models and higher effort cost more and run slower, so drop to a sim Context ------- -A language model has no memory of its own. Each time you send a message, the model re-reads the **entire** conversation so far — every message, every file it has opened, and every command's output. That transcript is bounded by a fixed **context window**, and model performance *degrades as the window fills*: Claude starts to "forget" earlier instructions and make more mistakes. Aim for a high-quality, focused context; a shorter context generally yields better results. Reference: `How Claude Code works `__. +A language model has no memory of its own. Each time you send a message, the model re-reads the **entire** conversation so far — every message, every file or document it has opened, and (in Claude Code) every command's output. That transcript is bounded by a fixed **context window** — roughly 200,000 tokens on most plans, larger on some Enterprise plans — and model performance *degrades as the window fills*: Claude starts to "forget" earlier instructions and make more mistakes. Aim for a high-quality, focused context; a shorter context generally yields better results. Reference: `Usage and length limits `__. -When a Claude Code session approaches the limit, it **compacts** the context — summarizing older turns to free space — which can lose detail. To work with this rather than against it: +When a conversation approaches the limit, Claude **compacts** it — automatically summarizing older turns to free space and keep going. This happens across the products, including the chat apps and Claude Code, and summarizing can lose detail. So the most reliable habit on any surface is to **start a fresh conversation for an unrelated task**: keep each conversation focused, and carry forward only what matters. The trade-off is that Claude "forgets" the previous thread — see below for how to make starting fresh cheap. + +In Claude Code +~~~~~~~~~~~~~~ + +Claude Code gives you direct control over the context window: - See what is using the window with ``/context``, and compact deliberately with ``/compact`` (optionally ``/compact focus on the API changes``) instead of waiting for automatic compaction. -- Start a fresh conversation (``/clear``) between unrelated tasks. The trade-off is that Claude "forgets" everything; carry forward only what matters. +- Reset the context between unrelated tasks with ``/clear``. - Roll back to an earlier, cleaner point with ``/rewind`` (or press ``Esc`` twice) instead of correcting the same mistake repeatedly. - For a quick aside that shouldn't bloat the transcript, use ``/btw``. -Persist context *across* sessions so that clearing or starting fresh is cheap: +Persisting context across sessions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Both the apps and Claude Code let you carry context across conversations, so starting fresh is cheap: + +- In the **Claude apps**, a **Project** retains instructions and uploaded files across chats. +- In **Claude Code**, a ``CLAUDE.md`` file (generate a starting point with ``/init``) gives every session the same project context, and **Skills** load task-specific instructions on demand. These are, in effect, a boilerplate first prompt that is always present — though the harness gives them somewhat higher priority than text you paste in. Reference: `Memory `__. -- A ``CLAUDE.md`` file (generate a starting point with ``/init``) gives every session the same project context. **Skills** load task-specific instructions on demand. These are, in effect, a boilerplate first prompt that is always present — though the harness gives them somewhat higher priority than text you paste in. Keep them short: an over-long ``CLAUDE.md`` or a pile of uploaded documents *adds* noise and reduces adherence. Reference: `Memory `__. -- **Projects** are a feature of the Claude *apps*, not Claude Code; they retain instructions and uploaded files across chats. Claude Code's equivalent is ``CLAUDE.md`` plus skills. +Either way, keep it lean: an over-long set of instructions or a pile of uploaded documents *adds* noise and reduces the quality of Claude's answers, so don't overdo it. -Two further effects on context: +Two further effects on context apply everywhere: - "Thinking" reasoning consumes context, because the model generates reasoning that it then re-reads before answering. Use simpler models or lower effort for simpler tasks. - Non-English text reportedly uses more tokens than English for the same content, so it fills the window faster. From f5d05ebe5d94657a0ab0825f3c88e4551d1908df Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 20 Jun 2026 23:23:14 +0000 Subject: [PATCH 04/23] Use verb-clause headings; link app memory features Rename the guidance sections to verb clauses (Select your task, Choose the tool/model, Manage the context, Prompt effectively, Watch for sycophancy, Work securely and responsibly). Under "Persist context across sessions", add and link the Claude apps' profile instructions, memory, and projects. Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_0125gpj95EzqfeMYBMWscJae --- docs/agents/index.rst | 38 +++++++++++++++++++++----------------- 1 file changed, 21 insertions(+), 17 deletions(-) diff --git a/docs/agents/index.rst b/docs/agents/index.rst index fb389e3..fd101b0 100644 --- a/docs/agents/index.rst +++ b/docs/agents/index.rst @@ -10,15 +10,15 @@ This page explains how to get good results from Claude — both the chat apps an If you had a poor experience with these tools, attend office hours before concluding that they don't work for your task: a small change in how you use them often makes the difference. -Task selection --------------- +Select your task +---------------- Claude is most useful on tasks where it can *use tools* — read your files, run commands, search the codebase, and check its own work — rather than answering from memory as a pure language model. Anthropic invests heavily in this tooling, and the results are noticeably better when Claude can act and verify than when it only predicts text. You can tell which mode it is in from the interface: a chat that only writes prose is acting as a language model, whereas a session that reads files, runs commands, and reports what it found is using tools. Prefer Claude for tasks that have a way to verify the result — a test suite, a build, a screenshot to compare, a script whose output you can check. Give it that check up front, and it can iterate to a working answer instead of stopping at the first plausible one. Reference: `Give Claude a way to verify its work `__. -Tools ------ +Choose the tool +--------------- Match the tool to the task: @@ -37,8 +37,8 @@ Match the tool to the task: These surfaces evolve quickly, and some are in research preview. Confirm the current name, availability, and capabilities of any surface against the `official documentation `__ before relying on it. -Models ------- +Choose the model +---------------- Use the most capable model available to you, and the most thorough reasoning setting for demanding work. @@ -47,8 +47,8 @@ Use the most capable model available to you, and the most thorough reasoning set More capable models and higher effort cost more and run slower, so drop to a simpler model or lower effort for routine, low-stakes tasks. -Context -------- +Manage the context +------------------- A language model has no memory of its own. Each time you send a message, the model re-reads the **entire** conversation so far — every message, every file or document it has opened, and (in Claude Code) every command's output. That transcript is bounded by a fixed **context window** — roughly 200,000 tokens on most plans, larger on some Enterprise plans — and model performance *degrades as the window fills*: Claude starts to "forget" earlier instructions and make more mistakes. Aim for a high-quality, focused context; a shorter context generally yields better results. Reference: `Usage and length limits `__. @@ -64,12 +64,16 @@ Claude Code gives you direct control over the context window: - Roll back to an earlier, cleaner point with ``/rewind`` (or press ``Esc`` twice) instead of correcting the same mistake repeatedly. - For a quick aside that shouldn't bloat the transcript, use ``/btw``. -Persisting context across sessions -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Persist context across sessions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Both the apps and Claude Code let you carry context across conversations, so starting fresh is cheap: -- In the **Claude apps**, a **Project** retains instructions and uploaded files across chats. +- In the **Claude apps**, several features carry context for you: + + - `Profile instructions `__ apply to *all* your conversations — Claude's standing profile of who you are and how you like to work. + - `Memory `__, when enabled, lets Claude summarize and reuse context from your past chats. Toggle it (and use incognito chats) under *Settings → Capabilities*. + - A `Project `__ retains instructions and uploaded files across the chats within it, with its own scoped memory. - In **Claude Code**, a ``CLAUDE.md`` file (generate a starting point with ``/init``) gives every session the same project context, and **Skills** load task-specific instructions on demand. These are, in effect, a boilerplate first prompt that is always present — though the harness gives them somewhat higher priority than text you paste in. Reference: `Memory `__. Either way, keep it lean: an over-long set of instructions or a pile of uploaded documents *adds* noise and reduces the quality of Claude's answers, so don't overdo it. @@ -79,8 +83,8 @@ Two further effects on context apply everywhere: - "Thinking" reasoning consumes context, because the model generates reasoning that it then re-reads before answering. Use simpler models or lower effort for simpler tasks. - Non-English text reportedly uses more tokens than English for the same content, so it fills the window faster. -Prompting ---------- +Prompt effectively +------------------ Provide as much *relevant* detail as is practical up front. A complete first prompt avoids a long back-and-forth that fills the context with corrections and changes of direction, which tends to confuse the model and lower the quality of its output. @@ -91,13 +95,13 @@ A few habits that reliably help: - Give **example outputs** to follow. Claude is not an oracle; showing the shape of a good answer works better than describing it. - If you don't yet know what you're asking for, use one session to refine the idea, then ask Claude to write a clean prompt for a fresh conversation. -Sycophancy ----------- +Watch for sycophancy +-------------------- Be wary of sycophancy. Generative models are trained to be agreeable and positive, and there is no reliable way to turn this off. Do not read Claude's enthusiasm as validation of your idea or its own output. When you need a genuine critique, ask for it explicitly, or have a *fresh* session review the work — a separate context that didn't produce the work evaluates it more honestly than the one that did. -Security and responsibility ---------------------------- +Work securely and responsibly +------------------------------ Risks ~~~~~ From 22586a3761bde34f088bce28437105c27d0d7bfc Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 21 Jun 2026 00:06:28 +0000 Subject: [PATCH 05/23] Add Claude Code page; move code-specific guidance off the Claude page Add docs/agents/claude-code.rst (nested under Claude): choosing a project and task, setup (CLAUDE.md, plan mode, devcontainer), planning, steering, and the code-specific security policy (permission/deny rules, SSH-key caveat, no production access, log hygiene, admin settings) and disclosure tags (__generated_by__, __generated_at__, __review_status__) with the maintaining hooks. Worktrees, MCP servers, and cost tracking are admonitions rather than sections. Slim the Claude page's "Work securely and responsibly" to surface-agnostic guidance and link to the Claude Code page for the codebase specifics. Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_0125gpj95EzqfeMYBMWscJae --- docs/agents/claude-code.rst | 101 ++++++++++++++++++++++++++++++++++++ docs/agents/index.rst | 29 ++++------- 2 files changed, 112 insertions(+), 18 deletions(-) create mode 100644 docs/agents/claude-code.rst diff --git a/docs/agents/claude-code.rst b/docs/agents/claude-code.rst new file mode 100644 index 0000000..5d5ec31 --- /dev/null +++ b/docs/agents/claude-code.rst @@ -0,0 +1,101 @@ +Claude Code +=========== + +.. seealso:: + + - Anthropic's `Claude Code best practices `__ and `how Claude Code works `__ + - Anthropic's `prompting best practices `__ + - Simon Willison on `coding agents `__ + - `Agent Skills `__ (an emerging open standard) and the `CLAUDE.md management plugin `__ + +Claude Code is OCP's default coding agent: it runs in a terminal, so it needs no shared editor or IDE, and it gives access to the strongest models. This page is the developer's how-to for using it on OCP's repositories. For guidance that applies to all of Claude's tools — choosing a model, managing context, prompting, and sycophancy — see :doc:`index`. + +Choose a project +---------------- + +Claude Code works best in a project that can check its own work, so prefer a repository: + +- With high **test coverage**. If coverage is low, have the agent add tests first. +- With **soundness checks**, such as the Rust compiler or a Python type checker. If Python type annotations are missing, have the agent add them first. +- With strict **linters and formatters**. OCP's default is to enable all rules in Ruff and cargo. + +Choose a task +------------- + +Choose tasks where **you are the expert**. Do not ask Claude to build or solve something you could not do yourself with your current knowledge: you need to be able to judge the result. + +Claude Code is especially good at complex **refactoring**, for example: + +- rewriting contributed code in the style of the rest of the file or project +- reducing duplication, single-use functions, and single-use or single-letter variables +- extracting methods + +See :doc:`index` for choosing between Claude's tools in the first place. + +Set up Claude Code +------------------ + +Give Claude Code persistent context with a ``CLAUDE.md`` file (see :doc:`index` for how this relates to the context window): + +- A user-level ``~/.claude/CLAUDE.md`` for machine-wide preferences, for example: + + .. code-block:: none + + - Always use `uv` to run Python scripts and manage packages and virtual environments + - Use `uv run` instead of `python` or `python3` + - Run `ruff format` after generating code + +- A project ``CLAUDE.md`` for project-specific context: a description of the project (if starting from scratch) and links to relevant documentation, such as the APIs you will use. + +Use **plan mode** (press :kbd:`Shift+Tab` to cycle to it) for complex or unfamiliar changes, so Claude explores and proposes a plan before editing. To run Claude Code in a container, use the `devcontainer `__. + +.. tip:: + + Prefer to work **without MCP servers** at first. They are easy to pile on, but each one fills the context with "noise", makes the agent harder to steer, and can duplicate functionality the agent already has — so add one only to solve a real problem you have. When the agent has a terminal, a script or ``Makefile`` it can run is often simpler. Servers that have proven useful include `Playwright `__, the `GitHub MCP server `__, `Serena `__ (a language server), and `Context7 `__ (up-to-date dependency documentation). Reference: `MCP `__. + +.. note:: + + OCP is on subscription plans, so token cost is not a concern. Out of curiosity, ``npx ccusage`` reports your token usage and the equivalent direct-API cost. + +Plan the work +------------- + +For a complex request, write a **specification** first, and ask Claude to keep it updated as it makes progress. A cheaper or faster model can do this planning. `This blog post `__ has examples. See :doc:`index` for refining an idea into a prompt before implementing. + +Steer the agent +--------------- + +- Agents tend to **anchor** to a direction. When you steer Claude off one, delete any code it generated down that path, or it tends to drift back. +- Work in small steps: **stage** accepted changes with ``git add`` between prompts, and review incremental changes with ``git diff``. +- Stop Claude with :kbd:`Esc` as soon as it goes off track, then redirect. + +.. tip:: + + Use `git worktree `__ so that you and the agent can work on the repository at the same time, independently. See the :doc:`../git/index`. + +Work securely and responsibly +----------------------------- + +.. seealso:: + + :doc:`index` covers the responsibilities that apply to all of Claude's tools. This section covers what is specific to working in a codebase. + +Limit permissions +~~~~~~~~~~~~~~~~~~ + +Keep approval prompts on, and keep ``bypassPermissions`` mode (formerly "dangerously skip permissions") disabled. Add ``permissions.deny`` rules for sensitive paths — at minimum ``pillar/private`` and ``salt/private`` — and remember that the Bash tool can read files such as ``~/.ssh``, so deny what Claude should never see. **Never give the agent access to production.** If you use Claude to debug logs, ensure those logs don't contain security, privacy, or confidential details — the same standard you apply to data sent to Sentry. Administrators manage Claude's GitHub access and enforce organization-wide policy (including disabling ``bypassPermissions`` mode) from the `Claude Code admin settings `__. Reference: `Permissions `__. + +Disclose generated code +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Mark unreviewed AI-generated code so that reviewers and maintainers know what has and hasn't been checked, using all three tags together: + +.. code-block:: python + + __generated_by__ = "Claude Code" + __generated_at__ = "2026-06-21" + __review_status__ = "unreviewed" + +A `PostToolUse hook `__ can maintain these automatically — refreshing ``__generated_at__`` while a file is still marked ``unreviewed``, and running ``ruff format`` after each edit. A companion ``PreToolUse`` hook can rewrite ``python`` and ``pip`` commands to their ``uv`` equivalents, enforcing the preference in your ``CLAUDE.md``. + +It is reasonable to skip thorough review only for low-stakes code: a proof of concept, a prototype, a one-time script, or a non-critical code path. Review anything that reaches a critical path. diff --git a/docs/agents/index.rst b/docs/agents/index.rst index fd101b0..8b92e40 100644 --- a/docs/agents/index.rst +++ b/docs/agents/index.rst @@ -103,30 +103,23 @@ Be wary of sycophancy. Generative models are trained to be agreeable and positiv Work securely and responsibly ------------------------------ -Risks -~~~~~ +Claude's main risks are autonomous operation, exposure of secrets or confidential data, and — over the longer term — skill atrophy from delegating work you no longer practice. OCP's existing practices cover much of this: secrets are centralized, and risky "skip all permissions" modes are disabled. Two rules apply on every surface: -The main risks are autonomous operation, over-broad permissions, and exposure of secrets or confidential data — for example, a shell command can read your SSH keys, and a debugging session can pull sensitive values into logs. A subtler, longer-term risk is skill atrophy from delegating work you no longer practice. +- **Never point Claude at production or confidential systems** — including a browser extension pointed at an authenticated session. +- **Don't expose confidential data.** Treat anything Claude can read — files, documents, logs — as in scope, and keep secrets, personal data, and confidential details out of what you share. -Mitigations -~~~~~~~~~~~ - -Existing OCP practice already covers much of this: secrets are centralized, and ``bypassPermissions`` mode (formerly "dangerously skip permissions") is disabled. Beyond that: +.. attention:: -- **Limit permissions.** Keep approval prompts on, and add ``permissions.deny`` rules for sensitive paths — at minimum ``pillar/private`` and ``salt/private``. Remember that the Bash tool can read files such as ``~/.ssh``, so deny what Claude should never see. Reference: `Permissions `__. -- **Never give agents access to production.** -- **Don't leak through logs.** If you use Claude to debug logs, ensure those logs don't contain security, privacy, or confidential details. They shouldn't already — the same standard you apply to data sent to Sentry. + You are responsible for whatever you submit, whether or not Claude wrote it. -Responsibility -~~~~~~~~~~~~~~ +Disclose unreviewed AI-generated work so that reviewers know what has and hasn't been checked. It is reasonable to skip thorough review only for low-stakes output: a proof of concept, a prototype, a one-time script, or a non-critical code path. Review anything that reaches a critical path. -.. attention:: +.. seealso:: - You are responsible for code you submit, whether or not Claude wrote it. + When working in a codebase, see :doc:`claude-code` for OCP's permission and deny rules, the SSH-key caveat, the disclosure tags, and other Claude Code specifics. -Disclose unreviewed AI-generated code — for example, with a ``__generated_by__`` tag or a commit trailer — so reviewers and maintainers know what has and hasn't been checked. It is reasonable to skip thorough review only for low-stakes code: a proof of concept, a prototype, a one-time script, or a non-critical code path. Review anything that reaches a critical path. +.. toctree:: + :hidden: -Administration -~~~~~~~~~~~~~~ + Claude Code -Administrators manage Claude's GitHub access from the `Claude Code admin settings `__ and can enforce organization-wide policy (including disabling ``bypassPermissions`` mode) through managed settings. Reference: `Managed settings `__. From d598c603371cbaeeaf26ae0898a3a82363650346 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 21 Jun 2026 00:17:57 +0000 Subject: [PATCH 06/23] Include full hook scripts in the Claude Code page Add the settings.json registration and the rewrite-python-to-uv.sh and python-post-write.sh hook scripts as code blocks under "Disclose generated code". Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_0125gpj95EzqfeMYBMWscJae --- docs/agents/claude-code.rst | 62 ++++++++++++++++++++++++++++++++++++- 1 file changed, 61 insertions(+), 1 deletion(-) diff --git a/docs/agents/claude-code.rst b/docs/agents/claude-code.rst index 5d5ec31..c3901a3 100644 --- a/docs/agents/claude-code.rst +++ b/docs/agents/claude-code.rst @@ -96,6 +96,66 @@ Mark unreviewed AI-generated code so that reviewers and maintainers know what ha __generated_at__ = "2026-06-21" __review_status__ = "unreviewed" -A `PostToolUse hook `__ can maintain these automatically — refreshing ``__generated_at__`` while a file is still marked ``unreviewed``, and running ``ruff format`` after each edit. A companion ``PreToolUse`` hook can rewrite ``python`` and ``pip`` commands to their ``uv`` equivalents, enforcing the preference in your ``CLAUDE.md``. +A `PostToolUse hook `__ can maintain these tags automatically — refreshing ``__generated_at__`` while a file is still marked ``unreviewed``, and running ``ruff format`` after each edit. A companion ``PreToolUse`` hook can rewrite ``python`` and ``pip`` commands to their ``uv`` equivalents, enforcing the preference in your ``CLAUDE.md``. Register both in ``~/.claude/settings.json`` (adjust the paths and, on Linux, the ``sed -i`` syntax for your system): + +.. code-block:: json + + { + "hooks": { + "PreToolUse": [ + { + "matcher": "Bash", + "hooks": [ + { + "type": "command", + "command": "/home/USER/.claude/hooks/rewrite-python-to-uv.sh" + } + ] + } + ], + "PostToolUse": [ + { + "matcher": "Write|Edit", + "hooks": [ + { + "type": "command", + "command": "/home/USER/.claude/hooks/python-post-write.sh" + } + ] + } + ] + } + } + +``rewrite-python-to-uv.sh``: + +.. code-block:: sh + + #!/bin/sh + # Rewrites python/python3/pip/pip3 commands to use uv equivalents. + + cmd=$(jq -r '.tool_input.command // empty') + + if echo "$cmd" | grep -qE '^(python3?|pip3?) '; then + echo "$cmd" | sed -E 's|^python3? |uv run python |; s|^pip3? |uv pip |' | jq -R '{"hookSpecificOutput": {"hookEventName": "PreToolUse", "updatedInput": {"command": .}}}' + fi + +``python-post-write.sh``: + +.. code-block:: sh + + #!/bin/sh + # After Write/Edit on Python files, update __generated_at__ if unreviewed, then run ruff format. + + file=$(jq -r '.tool_input.file_path // empty') + + case "$file" in + *.py) + if head -5 "$file" | grep -q '__review_status__ = "unreviewed"'; then + sed -i '' "s|^__generated_at__ = \".*\"|__generated_at__ = \"$(date +%Y-%m-%d)\"|" "$file" + fi + ruff format "$file" 2>/dev/null || true + ;; + esac It is reasonable to skip thorough review only for low-stakes code: a proof of concept, a prototype, a one-time script, or a non-critical code path. Review anything that reaches a critical path. From 00268a1880dd9760682ce6cf9bac74702e4903a6 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 21 Jun 2026 11:05:04 +0000 Subject: [PATCH 07/23] Clarify that apps memory is Claude-managed, not verbatim Explain that the Claude apps' memory is a running summary Claude manages and rewrites (scoped per project), unlike user-authored profile/project instructions, which apply verbatim. Direct readers to instructions or CLAUDE.md for anything that must persist exactly. Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_0125gpj95EzqfeMYBMWscJae --- docs/agents/index.rst | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/agents/index.rst b/docs/agents/index.rst index 8b92e40..b0d02dc 100644 --- a/docs/agents/index.rst +++ b/docs/agents/index.rst @@ -72,10 +72,14 @@ Both the apps and Claude Code let you carry context across conversations, so sta - In the **Claude apps**, several features carry context for you: - `Profile instructions `__ apply to *all* your conversations — Claude's standing profile of who you are and how you like to work. - - `Memory `__, when enabled, lets Claude summarize and reuse context from your past chats. Toggle it (and use incognito chats) under *Settings → Capabilities*. + - `Memory `__, when enabled, lets Claude carry context from your past chats. It is scoped — each Project has its own memory, separate from your non-project chats — and you can view, edit, or clear it (and use incognito chats) under *Settings → Capabilities*. - A `Project `__ retains instructions and uploaded files across the chats within it, with its own scoped memory. - In **Claude Code**, a ``CLAUDE.md`` file (generate a starting point with ``/init``) gives every session the same project context, and **Skills** load task-specific instructions on demand. These are, in effect, a boilerplate first prompt that is always present — though the harness gives them somewhat higher priority than text you paste in. Reference: `Memory `__. +.. note:: + + Profile and project instructions are not the same as memory. *You* write instructions, and Claude applies them verbatim to every relevant conversation. **Memory, by contrast, is managed by Claude**: it is a running *summary* of your past chats, not an exact or permanent record. If you ask Claude to remember something, expect it to be reworded, merged with other notes, or eventually dropped as the summary is rewritten. For anything that must persist exactly, write it as a profile or project instruction — or, in Claude Code, in ``CLAUDE.md``. + Either way, keep it lean: an over-long set of instructions or a pile of uploaded documents *adds* noise and reduces the quality of Claude's answers, so don't overdo it. Two further effects on context apply everywhere: From 30aebebf651fc5c718dbfc692037db306f07a676 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 21 Jun 2026 11:07:33 +0000 Subject: [PATCH 08/23] Clarify that project memory is isolated from account memory State explicitly that inside a Project, Claude uses only that Project's memory, not account-wide memory from other chats, and that general memory covers only non-project chats. Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_0125gpj95EzqfeMYBMWscJae --- docs/agents/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/agents/index.rst b/docs/agents/index.rst index b0d02dc..a7d5284 100644 --- a/docs/agents/index.rst +++ b/docs/agents/index.rst @@ -72,7 +72,7 @@ Both the apps and Claude Code let you carry context across conversations, so sta - In the **Claude apps**, several features carry context for you: - `Profile instructions `__ apply to *all* your conversations — Claude's standing profile of who you are and how you like to work. - - `Memory `__, when enabled, lets Claude carry context from your past chats. It is scoped — each Project has its own memory, separate from your non-project chats — and you can view, edit, or clear it (and use incognito chats) under *Settings → Capabilities*. + - `Memory `__, when enabled, lets Claude carry context from your past chats. It is **scoped and isolated**: inside a Project, Claude draws only on that Project's own memory — *not* on your account-wide memory from other chats — and your general memory covers only your non-project chats. So something Claude "remembered" in ordinary chats will not be available inside a Project, and vice versa. You can view, edit, or clear each memory (and use incognito chats) under *Settings → Capabilities*. - A `Project `__ retains instructions and uploaded files across the chats within it, with its own scoped memory. - In **Claude Code**, a ``CLAUDE.md`` file (generate a starting point with ``/init``) gives every session the same project context, and **Skills** load task-specific instructions on demand. These are, in effect, a boilerplate first prompt that is always present — though the harness gives them somewhat higher priority than text you paste in. Reference: `Memory `__. From ae25219ab4e496a014cd364573c6bed242a792d1 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 21 Jun 2026 11:10:28 +0000 Subject: [PATCH 09/23] Explain how to read apps memory; cite the memory behavior Describe the "View and edit memory" screen (and pause/reset/incognito), not just the toggle, and add a citation for the managed-summary behavior. Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_0125gpj95EzqfeMYBMWscJae --- docs/agents/index.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/agents/index.rst b/docs/agents/index.rst index a7d5284..920837f 100644 --- a/docs/agents/index.rst +++ b/docs/agents/index.rst @@ -72,13 +72,13 @@ Both the apps and Claude Code let you carry context across conversations, so sta - In the **Claude apps**, several features carry context for you: - `Profile instructions `__ apply to *all* your conversations — Claude's standing profile of who you are and how you like to work. - - `Memory `__, when enabled, lets Claude carry context from your past chats. It is **scoped and isolated**: inside a Project, Claude draws only on that Project's own memory — *not* on your account-wide memory from other chats — and your general memory covers only your non-project chats. So something Claude "remembered" in ordinary chats will not be available inside a Project, and vice versa. You can view, edit, or clear each memory (and use incognito chats) under *Settings → Capabilities*. + - `Memory `__, when enabled, lets Claude carry context from your past chats. It is **scoped and isolated**: inside a Project, Claude draws only on that Project's own memory — *not* on your account-wide memory from other chats — and your general memory covers only your non-project chats. So something Claude "remembered" in ordinary chats will not be available inside a Project, and vice versa. To read exactly what is stored, open *Settings → Capabilities → View and edit memory*, which lists everything Claude remembers; you can edit it there, or ask Claude in a chat to show or change what it remembers. The same screen lets you *pause* memory (keep it but stop reading or adding to it) or *reset* it (permanently delete everything, including project memories), and start *incognito* chats that are never remembered. - A `Project `__ retains instructions and uploaded files across the chats within it, with its own scoped memory. - In **Claude Code**, a ``CLAUDE.md`` file (generate a starting point with ``/init``) gives every session the same project context, and **Skills** load task-specific instructions on demand. These are, in effect, a boilerplate first prompt that is always present — though the harness gives them somewhat higher priority than text you paste in. Reference: `Memory `__. .. note:: - Profile and project instructions are not the same as memory. *You* write instructions, and Claude applies them verbatim to every relevant conversation. **Memory, by contrast, is managed by Claude**: it is a running *summary* of your past chats, not an exact or permanent record. If you ask Claude to remember something, expect it to be reworded, merged with other notes, or eventually dropped as the summary is rewritten. For anything that must persist exactly, write it as a profile or project instruction — or, in Claude Code, in ``CLAUDE.md``. + Profile and project instructions are not the same as memory. *You* write instructions, and Claude applies them verbatim to every relevant conversation. **Memory, by contrast, is managed by Claude**: it is a running *summary* of your past chats, not an exact or permanent record. If you ask Claude to remember something, expect it to be reworded, merged with other notes, or eventually dropped as the summary is rewritten. For anything that must persist exactly, write it as a profile or project instruction — or, in Claude Code, in ``CLAUDE.md``. Reference: `Chat search and memory `__. Either way, keep it lean: an over-long set of instructions or a pile of uploaded documents *adds* noise and reduces the quality of Claude's answers, so don't overdo it. From 9e5d2a1ea60b92fd0f0825f561d5ee8f90977a7c Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 21 Jun 2026 11:52:34 +0000 Subject: [PATCH 10/23] Clarify how attached files and project knowledge use context Explain that a file attached to a message loads in full (counts against the context window), while large Project knowledge is retrieved (RAG) rather than loaded wholesale. Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_0125gpj95EzqfeMYBMWscJae --- docs/agents/index.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/agents/index.rst b/docs/agents/index.rst index 920837f..a229fe8 100644 --- a/docs/agents/index.rst +++ b/docs/agents/index.rst @@ -52,6 +52,8 @@ Manage the context A language model has no memory of its own. Each time you send a message, the model re-reads the **entire** conversation so far — every message, every file or document it has opened, and (in Claude Code) every command's output. That transcript is bounded by a fixed **context window** — roughly 200,000 tokens on most plans, larger on some Enterprise plans — and model performance *degrades as the window fills*: Claude starts to "forget" earlier instructions and make more mistakes. Aim for a high-quality, focused context; a shorter context generally yields better results. Reference: `Usage and length limits `__. +Attached files contribute to that window in two different ways. A file you **attach to a message** is read in full, so it counts against the context window like pasted text (very large files may instead be handled in Claude's file environment rather than loaded). Files you add to a **Project's knowledge** behave differently: while the knowledge base is small enough to fit, Claude loads all of it, but once it grows past the window Claude switches to *retrieval* — searching the knowledge and pulling in only the relevant parts on demand. So a few attachments are always-present (and always-costing) context, whereas large project knowledge is searched rather than loaded wholesale. Reference: `RAG for projects `__. + When a conversation approaches the limit, Claude **compacts** it — automatically summarizing older turns to free space and keep going. This happens across the products, including the chat apps and Claude Code, and summarizing can lose detail. So the most reliable habit on any surface is to **start a fresh conversation for an unrelated task**: keep each conversation focused, and carry forward only what matters. The trade-off is that Claude "forgets" the previous thread — see below for how to make starting fresh cheap. In Claude Code From 65390ac349086aa61dab9179210e6e45571a128d Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 21 Jun 2026 12:12:08 +0000 Subject: [PATCH 11/23] Reorganize the context section into subsections Split "Manage the context" into general content (how context works, compaction, Claude's own context management) followed by subsections: Files and attachments (noting chat loads in full while Cowork and Claude Code read on demand), Models and thinking, Instructions and projects, Memory, and In Claude Code. Explain how telling Claude to remember something works. Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_0125gpj95EzqfeMYBMWscJae --- docs/agents/index.rst | 58 +++++++++++++++++++++++++++---------------- 1 file changed, 36 insertions(+), 22 deletions(-) diff --git a/docs/agents/index.rst b/docs/agents/index.rst index a229fe8..83cfee1 100644 --- a/docs/agents/index.rst +++ b/docs/agents/index.rst @@ -52,42 +52,56 @@ Manage the context A language model has no memory of its own. Each time you send a message, the model re-reads the **entire** conversation so far — every message, every file or document it has opened, and (in Claude Code) every command's output. That transcript is bounded by a fixed **context window** — roughly 200,000 tokens on most plans, larger on some Enterprise plans — and model performance *degrades as the window fills*: Claude starts to "forget" earlier instructions and make more mistakes. Aim for a high-quality, focused context; a shorter context generally yields better results. Reference: `Usage and length limits `__. -Attached files contribute to that window in two different ways. A file you **attach to a message** is read in full, so it counts against the context window like pasted text (very large files may instead be handled in Claude's file environment rather than loaded). Files you add to a **Project's knowledge** behave differently: while the knowledge base is small enough to fit, Claude loads all of it, but once it grows past the window Claude switches to *retrieval* — searching the knowledge and pulling in only the relevant parts on demand. So a few attachments are always-present (and always-costing) context, whereas large project knowledge is searched rather than loaded wholesale. Reference: `RAG for projects `__. +When a conversation approaches the limit, Claude **compacts** it — automatically summarizing older turns to free space and keep going. This happens across the products, including the chat apps and Claude Code, and summarizing can lose detail. So the most reliable habit on any surface is to **start a fresh conversation for an unrelated task**: keep each conversation focused, and carry forward only what matters. The trade-off is that Claude "forgets" the previous thread; the rest of this section covers what fills the window, what carries over, and how each tool helps. -When a conversation approaches the limit, Claude **compacts** it — automatically summarizing older turns to free space and keep going. This happens across the products, including the chat apps and Claude Code, and summarizing can lose detail. So the most reliable habit on any surface is to **start a fresh conversation for an unrelated task**: keep each conversation focused, and carry forward only what matters. The trade-off is that Claude "forgets" the previous thread — see below for how to make starting fresh cheap. +Claude also manages the window itself, not just you. Compaction is one example; in the agentic tools (Cowork and Claude Code) Claude searches with tools like ``grep`` and reads only the parts of a file it needs rather than loading whole files, and large project knowledge is retrieved on demand. The main thing that is *not* read selectively is a file you attach directly to a chat message, which loads in full (see below). -In Claude Code -~~~~~~~~~~~~~~ +Files and attachments +~~~~~~~~~~~~~~~~~~~~~~~ -Claude Code gives you direct control over the context window: +How a file reaches the model depends on the tool: -- See what is using the window with ``/context``, and compact deliberately with ``/compact`` (optionally ``/compact focus on the API changes``) instead of waiting for automatic compaction. -- Reset the context between unrelated tasks with ``/clear``. -- Roll back to an earlier, cleaner point with ``/rewind`` (or press ``Esc`` twice) instead of correcting the same mistake repeatedly. -- For a quick aside that shouldn't bloat the transcript, use ``/btw``. +- In the **chat apps**, a file you attach to a message is read **in full**, so it counts against the context window like pasted text — always present, and costing tokens every turn. (Very large files may instead be handled in Claude's file environment rather than loaded.) +- In **Cowork** and **Claude Code**, files are read **on demand**: Claude works agentically over the folders you give it access to, opening only the files it needs, so only what it actually reads enters the context. + +For a **Project's knowledge** (in the apps and Cowork), Claude loads the whole knowledge base while it is small enough to fit; once it grows past the window, Claude switches to *retrieval*, searching the knowledge and pulling in only the relevant parts. So large project knowledge is searched rather than loaded wholesale. Reference: `RAG for projects `__. + +Models and thinking +~~~~~~~~~~~~~~~~~~~~ + +- "Thinking" reasoning consumes context, because the model generates reasoning that it then re-reads before answering. Use simpler models or lower effort for simpler tasks. +- Non-English text reportedly uses more tokens than English for the same content, so it fills the window faster. -Persist context across sessions -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Instructions and projects +~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Both the apps and Claude Code let you carry context across conversations, so starting fresh is cheap: +To carry context across conversations in the apps without re-explaining it each time: -- In the **Claude apps**, several features carry context for you: +- `Profile instructions `__ apply to *all* your conversations — your standing profile of who you are and how you like to work. +- A `Project `__ bundles standing instructions, a knowledge base, and its own memory for one area of work. Its instructions apply to every chat **within that project**, and a Cowork project can also point at local folders. - - `Profile instructions `__ apply to *all* your conversations — Claude's standing profile of who you are and how you like to work. - - `Memory `__, when enabled, lets Claude carry context from your past chats. It is **scoped and isolated**: inside a Project, Claude draws only on that Project's own memory — *not* on your account-wide memory from other chats — and your general memory covers only your non-project chats. So something Claude "remembered" in ordinary chats will not be available inside a Project, and vice versa. To read exactly what is stored, open *Settings → Capabilities → View and edit memory*, which lists everything Claude remembers; you can edit it there, or ask Claude in a chat to show or change what it remembers. The same screen lets you *pause* memory (keep it but stop reading or adding to it) or *reset* it (permanently delete everything, including project memories), and start *incognito* chats that are never remembered. - - A `Project `__ retains instructions and uploaded files across the chats within it, with its own scoped memory. -- In **Claude Code**, a ``CLAUDE.md`` file (generate a starting point with ``/init``) gives every session the same project context, and **Skills** load task-specific instructions on demand. These are, in effect, a boilerplate first prompt that is always present — though the harness gives them somewhat higher priority than text you paste in. Reference: `Memory `__. +Instructions are always present and applied **verbatim**, so keep them lean: an over-long set of instructions *adds* noise and reduces the quality of Claude's answers. + +Memory +~~~~~~ + +`Memory `__, when enabled, lets Claude carry context from your past chats. It is **scoped and isolated**: inside a Project, Claude draws only on that Project's own memory — *not* on your account-wide memory from other chats — and your general memory covers only your non-project chats. So something Claude "remembered" in ordinary chats will not be available inside a Project, and vice versa. You add to memory in two ways: by telling Claude in any chat to remember something (for example, "remember that I prefer X"), which it writes into the summary without leaving the conversation and applies from your next chat; or by editing the summary yourself. To read or edit exactly what is stored, open *Settings → Capabilities → View and edit memory*, which lists everything Claude remembers (you can also ask Claude in a chat to show it). The same screen lets you *pause* memory (keep it but stop reading or adding to it) or *reset* it (permanently delete everything, including project memories), and start *incognito* chats that are never remembered. .. note:: - Profile and project instructions are not the same as memory. *You* write instructions, and Claude applies them verbatim to every relevant conversation. **Memory, by contrast, is managed by Claude**: it is a running *summary* of your past chats, not an exact or permanent record. If you ask Claude to remember something, expect it to be reworded, merged with other notes, or eventually dropped as the summary is rewritten. For anything that must persist exactly, write it as a profile or project instruction — or, in Claude Code, in ``CLAUDE.md``. Reference: `Chat search and memory `__. + Instructions are not the same as memory. *You* write instructions, and Claude applies them verbatim to every relevant conversation. **Memory, by contrast, is managed by Claude**: it is a running *summary* of your past chats, not an exact or permanent record. If you ask Claude to remember something, expect it to be reworded, merged with other notes, or eventually dropped as the summary is rewritten. For anything that must persist exactly, write it as a profile or project instruction — or, in Claude Code, in ``CLAUDE.md``. Reference: `Chat search and memory `__. -Either way, keep it lean: an over-long set of instructions or a pile of uploaded documents *adds* noise and reduces the quality of Claude's answers, so don't overdo it. +In Claude Code +~~~~~~~~~~~~~~ -Two further effects on context apply everywhere: +Claude Code gives you direct control over the context window: -- "Thinking" reasoning consumes context, because the model generates reasoning that it then re-reads before answering. Use simpler models or lower effort for simpler tasks. -- Non-English text reportedly uses more tokens than English for the same content, so it fills the window faster. +- See what is using the window with ``/context``, and compact deliberately with ``/compact`` (optionally ``/compact focus on the API changes``) instead of waiting for automatic compaction. +- Reset the context between unrelated tasks with ``/clear``. +- Roll back to an earlier, cleaner point with ``/rewind`` (or press ``Esc`` twice) instead of correcting the same mistake repeatedly. +- For a quick aside that shouldn't bloat the transcript, use ``/btw``. + +To carry context across sessions, a ``CLAUDE.md`` file (generate a starting point with ``/init``) gives every session the same project context, and **Skills** load task-specific instructions on demand. These are, in effect, a boilerplate first prompt that is always present — though the harness gives them somewhat higher priority than text you paste in. As with apps instructions, keep them lean. Reference: `Memory `__. Prompt effectively ------------------ From 6e0cfd365ab53bb2f5250327e3e41c13322ff4b5 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 21 Jun 2026 12:17:57 +0000 Subject: [PATCH 12/23] Clarify chat attachment limits and project-chat attachments Note that chat caps attachment size and returns a length error rather than silently dropping earlier context, and that a file attached inside a Project chat is context for that conversation only, not added to project knowledge. Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_0125gpj95EzqfeMYBMWscJae --- docs/agents/index.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/agents/index.rst b/docs/agents/index.rst index 83cfee1..47de67f 100644 --- a/docs/agents/index.rst +++ b/docs/agents/index.rst @@ -61,11 +61,13 @@ Files and attachments How a file reaches the model depends on the tool: -- In the **chat apps**, a file you attach to a message is read **in full**, so it counts against the context window like pasted text — always present, and costing tokens every turn. (Very large files may instead be handled in Claude's file environment rather than loaded.) +- In the **chat apps**, a file you attach to a message is read **in full**, so it counts against the context window like pasted text — always present, and costing tokens every turn. (Very large files may instead be handled in Claude's file environment rather than loaded.) Attaching a file inside a Project chat works the same way: it is context for that one conversation, *not* added to the Project's knowledge. - In **Cowork** and **Claude Code**, files are read **on demand**: Claude works agentically over the folders you give it access to, opening only the files it needs, so only what it actually reads enters the context. For a **Project's knowledge** (in the apps and Cowork), Claude loads the whole knowledge base while it is small enough to fit; once it grows past the window, Claude switches to *retrieval*, searching the knowledge and pulling in only the relevant parts. So large project knowledge is searched rather than loaded wholesale. Reference: `RAG for projects `__. +The apps guard against an oversized attachment rather than silently discarding earlier messages: each file is capped (around 30 MB), and if a message and its attachment would exceed the context window, Claude returns a length error and prompts you to shorten the input or start a new chat. Reference: `Usage and length limits `__. + Models and thinking ~~~~~~~~~~~~~~~~~~~~ From acb51a554231bdd82fbc2616c4071f1f353f7d57 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 21 Jun 2026 12:19:58 +0000 Subject: [PATCH 13/23] Cite the source pages for attachment size cap and length error Reference Upload files (30 MB cap) and Troubleshoot error messages alongside Usage and length limits, so each attachment-handling claim is verifiable. Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_0125gpj95EzqfeMYBMWscJae --- docs/agents/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/agents/index.rst b/docs/agents/index.rst index 47de67f..39a7ce8 100644 --- a/docs/agents/index.rst +++ b/docs/agents/index.rst @@ -66,7 +66,7 @@ How a file reaches the model depends on the tool: For a **Project's knowledge** (in the apps and Cowork), Claude loads the whole knowledge base while it is small enough to fit; once it grows past the window, Claude switches to *retrieval*, searching the knowledge and pulling in only the relevant parts. So large project knowledge is searched rather than loaded wholesale. Reference: `RAG for projects `__. -The apps guard against an oversized attachment rather than silently discarding earlier messages: each file is capped (around 30 MB), and if a message and its attachment would exceed the context window, Claude returns a length error and prompts you to shorten the input or start a new chat. Reference: `Usage and length limits `__. +The apps guard against an oversized attachment rather than silently discarding earlier messages: each file is capped (around 30 MB), and if a message and its attachment would exceed the context window, Claude returns a length error and prompts you to shorten the input or start a new chat. References: `Upload files `__ (size cap), `Usage and length limits `__, and `Troubleshoot error messages `__. Models and thinking ~~~~~~~~~~~~~~~~~~~~ From c2032a0a0d932053cc9b281098a9a9d6eae19857 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 21 Jun 2026 12:23:40 +0000 Subject: [PATCH 14/23] Source the non-English token-usage claim Cite the API Glossary (a token is ~3.5 English characters, varying by language) and drop the "reportedly" hedge. Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_0125gpj95EzqfeMYBMWscJae --- docs/agents/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/agents/index.rst b/docs/agents/index.rst index 39a7ce8..030bcaa 100644 --- a/docs/agents/index.rst +++ b/docs/agents/index.rst @@ -72,7 +72,7 @@ Models and thinking ~~~~~~~~~~~~~~~~~~~~ - "Thinking" reasoning consumes context, because the model generates reasoning that it then re-reads before answering. Use simpler models or lower effort for simpler tasks. -- Non-English text reportedly uses more tokens than English for the same content, so it fills the window faster. +- Non-English text generally uses more tokens than English for the same content, so it fills the window faster: a token is roughly 3.5 English characters, but the exact number varies by language. Reference: `Glossary `__. Instructions and projects ~~~~~~~~~~~~~~~~~~~~~~~~~~~ From b0fa89e9e957105f6c5f5f84ef6ad927f966b723 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 21 Jun 2026 12:26:49 +0000 Subject: [PATCH 15/23] Trim tangential char-per-token figure Keep the language-varies-by-tokenization point (and its citation) but drop the English characters-per-token number, which was irrelevant to the claim. Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_0125gpj95EzqfeMYBMWscJae --- docs/agents/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/agents/index.rst b/docs/agents/index.rst index 030bcaa..37ad65c 100644 --- a/docs/agents/index.rst +++ b/docs/agents/index.rst @@ -72,7 +72,7 @@ Models and thinking ~~~~~~~~~~~~~~~~~~~~ - "Thinking" reasoning consumes context, because the model generates reasoning that it then re-reads before answering. Use simpler models or lower effort for simpler tasks. -- Non-English text generally uses more tokens than English for the same content, so it fills the window faster: a token is roughly 3.5 English characters, but the exact number varies by language. Reference: `Glossary `__. +- Non-English text generally uses more tokens than English for the same content — the number of characters per token varies by language — so it fills the window faster. Reference: `Glossary `__. Instructions and projects ~~~~~~~~~~~~~~~~~~~~~~~~~~~ From 55cfdef012161cba8a6f994ce0cf9af6f657e819 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 21 Jun 2026 12:28:23 +0000 Subject: [PATCH 16/23] Match token-usage claim to what the source supports The Glossary states token counts vary by language but not the direction, so state only that the language affects how fast the window fills. Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_0125gpj95EzqfeMYBMWscJae --- docs/agents/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/agents/index.rst b/docs/agents/index.rst index 37ad65c..48850a3 100644 --- a/docs/agents/index.rst +++ b/docs/agents/index.rst @@ -72,7 +72,7 @@ Models and thinking ~~~~~~~~~~~~~~~~~~~~ - "Thinking" reasoning consumes context, because the model generates reasoning that it then re-reads before answering. Use simpler models or lower effort for simpler tasks. -- Non-English text generally uses more tokens than English for the same content — the number of characters per token varies by language — so it fills the window faster. Reference: `Glossary `__. +- The same content can take a different number of tokens depending on the language, so the language you work in affects how quickly the window fills. Reference: `Glossary `__. Instructions and projects ~~~~~~~~~~~~~~~~~~~~~~~~~~~ From ff5d2d12ace4bca7775b9bd4c956fd8ddf1849ed Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 21 Jun 2026 14:38:50 +0000 Subject: [PATCH 17/23] Add a model/context/tools mental-model admonition MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Frame the page with the three primitives — model, context, tools — and note that skills, memory, projects, MCP, and subagents are variations on them. Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_0125gpj95EzqfeMYBMWscJae --- docs/agents/index.rst | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/agents/index.rst b/docs/agents/index.rst index 48850a3..653051a 100644 --- a/docs/agents/index.rst +++ b/docs/agents/index.rst @@ -10,6 +10,16 @@ This page explains how to get good results from Claude — both the chat apps an If you had a poor experience with these tools, attend office hours before concluding that they don't work for your task: a small change in how you use them often makes the difference. +.. admonition:: A mental model: model, context, and tools + + Three things explain most of how these products behave: + + - the **model** — the LLM that actually generates the response. More capable models reason better; see *Choose the model*. + - the **context** — everything the model can see for the current turn: your messages, your instructions, attached files, memory, and the output of any tools it has run. It is bounded by the context window and re-read every turn; see *Manage the context*. + - the **tools** — the actions the model can take beyond producing text, such as reading a file, running a shell command, searching the web, or editing code. Tools are what let Claude *act and verify* rather than only predict text. + + Most other features are variations on these three: skills, memory, projects, and ``CLAUDE.md`` shape what is in *context*; MCP servers add *tools*; a subagent is just another bundle of model, context, and tools. Understand these three and the rest follows. + Select your task ---------------- From 5cad0a1424209c6b84b47d67f7123c68f235718a Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 21 Jun 2026 14:39:31 +0000 Subject: [PATCH 18/23] Place RAG in the mental model Note that retrieval (RAG) is a tool that pulls relevant context in, as another example of features composing the model/context/tools primitives. Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_0125gpj95EzqfeMYBMWscJae --- docs/agents/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/agents/index.rst b/docs/agents/index.rst index 653051a..7335082 100644 --- a/docs/agents/index.rst +++ b/docs/agents/index.rst @@ -18,7 +18,7 @@ If you had a poor experience with these tools, attend office hours before conclu - the **context** — everything the model can see for the current turn: your messages, your instructions, attached files, memory, and the output of any tools it has run. It is bounded by the context window and re-read every turn; see *Manage the context*. - the **tools** — the actions the model can take beyond producing text, such as reading a file, running a shell command, searching the web, or editing code. Tools are what let Claude *act and verify* rather than only predict text. - Most other features are variations on these three: skills, memory, projects, and ``CLAUDE.md`` shape what is in *context*; MCP servers add *tools*; a subagent is just another bundle of model, context, and tools. Understand these three and the rest follows. + Most other features are variations on these three: skills, memory, projects, and ``CLAUDE.md`` shape what is in *context*; MCP servers add *tools*; retrieval (RAG) is a *tool* that pulls only the relevant *context* in; a subagent is just another bundle of model, context, and tools. Understand these three and the rest follows. Select your task ---------------- From c1991834a33c456c51807666dca5d2fa350ea6b4 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 21 Jun 2026 14:41:37 +0000 Subject: [PATCH 19/23] Rename "Choose the tool" to "Choose the product" and disambiguate Use "product" for the product/surface sense of "tool" (section heading, "these products", "match the product", "how each product helps", "depends on the product", "Claude's products") and keep "tool" only for the LLM-tool sense (the mental-model admonition, "use tools", the Bash tool, grep, hooks). Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_0125gpj95EzqfeMYBMWscJae --- docs/agents/claude-code.rst | 6 +++--- docs/agents/index.rst | 16 ++++++++-------- 2 files changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/agents/claude-code.rst b/docs/agents/claude-code.rst index c3901a3..8d31901 100644 --- a/docs/agents/claude-code.rst +++ b/docs/agents/claude-code.rst @@ -8,7 +8,7 @@ Claude Code - Simon Willison on `coding agents `__ - `Agent Skills `__ (an emerging open standard) and the `CLAUDE.md management plugin `__ -Claude Code is OCP's default coding agent: it runs in a terminal, so it needs no shared editor or IDE, and it gives access to the strongest models. This page is the developer's how-to for using it on OCP's repositories. For guidance that applies to all of Claude's tools — choosing a model, managing context, prompting, and sycophancy — see :doc:`index`. +Claude Code is OCP's default coding agent: it runs in a terminal, so it needs no shared editor or IDE, and it gives access to the strongest models. This page is the developer's how-to for using it on OCP's repositories. For guidance that applies to all of Claude's products — choosing a model, managing context, prompting, and sycophancy — see :doc:`index`. Choose a project ---------------- @@ -30,7 +30,7 @@ Claude Code is especially good at complex **refactoring**, for example: - reducing duplication, single-use functions, and single-use or single-letter variables - extracting methods -See :doc:`index` for choosing between Claude's tools in the first place. +See :doc:`index` for choosing between Claude's products in the first place. Set up Claude Code ------------------ @@ -78,7 +78,7 @@ Work securely and responsibly .. seealso:: - :doc:`index` covers the responsibilities that apply to all of Claude's tools. This section covers what is specific to working in a codebase. + :doc:`index` covers the responsibilities that apply to all of Claude's products. This section covers what is specific to working in a codebase. Limit permissions ~~~~~~~~~~~~~~~~~~ diff --git a/docs/agents/index.rst b/docs/agents/index.rst index 7335082..729b549 100644 --- a/docs/agents/index.rst +++ b/docs/agents/index.rst @@ -6,9 +6,9 @@ Claude - Anthropic's `Claude Code best practices `__ - Anthropic's `prompting best practices `__ -This page explains how to get good results from Claude — both the chat apps and `Claude Code `__ — and how to use it responsibly on OCP's work. These tools change quickly, so treat specific commands and model names as correct at the time of writing, and check the linked official documentation for current details. +This page explains how to get good results from Claude — both the chat apps and `Claude Code `__ — and how to use it responsibly on OCP's work. These products change quickly, so treat specific commands and model names as correct at the time of writing, and check the linked official documentation for current details. -If you had a poor experience with these tools, attend office hours before concluding that they don't work for your task: a small change in how you use them often makes the difference. +If you had a poor experience with these products, attend office hours before concluding that they don't work for your task: a small change in how you use them often makes the difference. .. admonition:: A mental model: model, context, and tools @@ -27,10 +27,10 @@ Claude is most useful on tasks where it can *use tools* — read your files, run Prefer Claude for tasks that have a way to verify the result — a test suite, a build, a screenshot to compare, a script whose output you can check. Give it that check up front, and it can iterate to a working answer instead of stopping at the first plausible one. Reference: `Give Claude a way to verify its work `__. -Choose the tool ---------------- +Choose the product +------------------ -Match the tool to the task: +Match the product to the task: - **Claude apps** (web, desktop, mobile) for chat: questions, drafting, and exploration that don't touch a repository. - `Claude Cowork `__, in the desktop app, for multi-step knowledge work over your local files and folders — especially working on or searching through long documents. It uses the same agentic approach as Claude Code, without the terminal. @@ -62,14 +62,14 @@ Manage the context A language model has no memory of its own. Each time you send a message, the model re-reads the **entire** conversation so far — every message, every file or document it has opened, and (in Claude Code) every command's output. That transcript is bounded by a fixed **context window** — roughly 200,000 tokens on most plans, larger on some Enterprise plans — and model performance *degrades as the window fills*: Claude starts to "forget" earlier instructions and make more mistakes. Aim for a high-quality, focused context; a shorter context generally yields better results. Reference: `Usage and length limits `__. -When a conversation approaches the limit, Claude **compacts** it — automatically summarizing older turns to free space and keep going. This happens across the products, including the chat apps and Claude Code, and summarizing can lose detail. So the most reliable habit on any surface is to **start a fresh conversation for an unrelated task**: keep each conversation focused, and carry forward only what matters. The trade-off is that Claude "forgets" the previous thread; the rest of this section covers what fills the window, what carries over, and how each tool helps. +When a conversation approaches the limit, Claude **compacts** it — automatically summarizing older turns to free space and keep going. This happens across the products, including the chat apps and Claude Code, and summarizing can lose detail. So the most reliable habit on any surface is to **start a fresh conversation for an unrelated task**: keep each conversation focused, and carry forward only what matters. The trade-off is that Claude "forgets" the previous thread; the rest of this section covers what fills the window, what carries over, and how each product helps. -Claude also manages the window itself, not just you. Compaction is one example; in the agentic tools (Cowork and Claude Code) Claude searches with tools like ``grep`` and reads only the parts of a file it needs rather than loading whole files, and large project knowledge is retrieved on demand. The main thing that is *not* read selectively is a file you attach directly to a chat message, which loads in full (see below). +Claude also manages the window itself, not just you. Compaction is one example; in Cowork and Claude Code, Claude searches with tools like ``grep`` and reads only the parts of a file it needs rather than loading whole files, and large project knowledge is retrieved on demand. The main thing that is *not* read selectively is a file you attach directly to a chat message, which loads in full (see below). Files and attachments ~~~~~~~~~~~~~~~~~~~~~~~ -How a file reaches the model depends on the tool: +How a file reaches the model depends on the product: - In the **chat apps**, a file you attach to a message is read **in full**, so it counts against the context window like pasted text — always present, and costing tokens every turn. (Very large files may instead be handled in Claude's file environment rather than loaded.) Attaching a file inside a Project chat works the same way: it is context for that one conversation, *not* added to the Project's knowledge. - In **Cowork** and **Claude Code**, files are read **on demand**: Claude works agentically over the folders you give it access to, opening only the files it needs, so only what it actually reads enters the context. From 02231f420508f07e9b67a5339eb3eb0e820296a2 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 21 Jun 2026 14:45:25 +0000 Subject: [PATCH 20/23] Add the two-levers takeaway after the mental model State that the two levers a user controls to improve output are managing context and improving the prompt, and that almost everything else feeds one of the two. Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_0125gpj95EzqfeMYBMWscJae --- docs/agents/index.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/agents/index.rst b/docs/agents/index.rst index 729b549..a1554fb 100644 --- a/docs/agents/index.rst +++ b/docs/agents/index.rst @@ -20,6 +20,8 @@ If you had a poor experience with these products, attend office hours before con Most other features are variations on these three: skills, memory, projects, and ``CLAUDE.md`` shape what is in *context*; MCP servers add *tools*; retrieval (RAG) is a *tool* that pulls only the relevant *context* in; a subagent is just another bundle of model, context, and tools. Understand these three and the rest follows. +From there, the two levers you actually control to improve Claude's output are **managing the context** and **improving your prompt** (see *Manage the context* and *Prompt effectively* below). The model is mostly a given — pick the most capable — and the tools come with the product, so almost everything else you do is really one of these two: skills, memory, projects, and files shape the *context*, while example outputs, specifications, and clearer instructions improve the *prompt*. + Select your task ---------------- From 552267e65866301a58f871ea920c5d7538b65198 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 21 Jun 2026 14:49:44 +0000 Subject: [PATCH 21/23] Move the two-levers takeaway to a closing recap Keep the mental-model admonition as orientation up top, and recap the two levers (managing context, improving prompts) plus the responsibility points in a closing "In short" admonition. Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_0125gpj95EzqfeMYBMWscJae --- docs/agents/index.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/agents/index.rst b/docs/agents/index.rst index a1554fb..79ddfac 100644 --- a/docs/agents/index.rst +++ b/docs/agents/index.rst @@ -20,8 +20,6 @@ If you had a poor experience with these products, attend office hours before con Most other features are variations on these three: skills, memory, projects, and ``CLAUDE.md`` shape what is in *context*; MCP servers add *tools*; retrieval (RAG) is a *tool* that pulls only the relevant *context* in; a subagent is just another bundle of model, context, and tools. Understand these three and the rest follows. -From there, the two levers you actually control to improve Claude's output are **managing the context** and **improving your prompt** (see *Manage the context* and *Prompt effectively* below). The model is mostly a given — pick the most capable — and the tools come with the product, so almost everything else you do is really one of these two: skills, memory, projects, and files shape the *context*, while example outputs, specifications, and clearer instructions improve the *prompt*. - Select your task ---------------- @@ -152,6 +150,10 @@ Disclose unreviewed AI-generated work so that reviewers know what has and hasn't When working in a codebase, see :doc:`claude-code` for OCP's permission and deny rules, the SSH-key caveat, the disclosure tags, and other Claude Code specifics. +.. admonition:: In short + + Model and tools are largely given — pick the most capable product and model — so improving Claude's output comes down to two levers: **managing the context** and **improving your prompt**. Almost everything else (skills, memory, projects, files, example outputs, specifications) feeds one of the two. The rest is judgement: watch for sycophancy, and keep secrets and production systems out of reach. + .. toctree:: :hidden: From 00857a16cca33c95150b92eca89f62d6f8fd8551 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 21 Jun 2026 15:20:21 +0000 Subject: [PATCH 22/23] State the Team-plan context window size Give the specific 200,000-token window and drop the Enterprise hedge. Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_0125gpj95EzqfeMYBMWscJae --- docs/agents/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/agents/index.rst b/docs/agents/index.rst index 79ddfac..5f0395f 100644 --- a/docs/agents/index.rst +++ b/docs/agents/index.rst @@ -60,7 +60,7 @@ More capable models and higher effort cost more and run slower, so drop to a sim Manage the context ------------------- -A language model has no memory of its own. Each time you send a message, the model re-reads the **entire** conversation so far — every message, every file or document it has opened, and (in Claude Code) every command's output. That transcript is bounded by a fixed **context window** — roughly 200,000 tokens on most plans, larger on some Enterprise plans — and model performance *degrades as the window fills*: Claude starts to "forget" earlier instructions and make more mistakes. Aim for a high-quality, focused context; a shorter context generally yields better results. Reference: `Usage and length limits `__. +A language model has no memory of its own. Each time you send a message, the model re-reads the **entire** conversation so far — every message, every file or document it has opened, and (in Claude Code) every command's output. That transcript is bounded by a fixed **context window** of 200,000 tokens, and model performance *degrades as the window fills*: Claude starts to "forget" earlier instructions and make more mistakes. Aim for a high-quality, focused context; a shorter context generally yields better results. Reference: `Usage and length limits `__. When a conversation approaches the limit, Claude **compacts** it — automatically summarizing older turns to free space and keep going. This happens across the products, including the chat apps and Claude Code, and summarizing can lose detail. So the most reliable habit on any surface is to **start a fresh conversation for an unrelated task**: keep each conversation focused, and carry forward only what matters. The trade-off is that Claude "forgets" the previous thread; the rest of this section covers what fills the window, what carries over, and how each product helps. From 189eb9cc2f304294a2679dadd0d66fbbb93017b4 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 21 Jun 2026 15:27:08 +0000 Subject: [PATCH 23/23] Note that memory can reinforce sycophancy Add that a recorded preference for agreement carries into new chats, so even starting fresh may not reset it. Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_0125gpj95EzqfeMYBMWscJae --- docs/agents/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/agents/index.rst b/docs/agents/index.rst index 5f0395f..fca266e 100644 --- a/docs/agents/index.rst +++ b/docs/agents/index.rst @@ -130,7 +130,7 @@ A few habits that reliably help: Watch for sycophancy -------------------- -Be wary of sycophancy. Generative models are trained to be agreeable and positive, and there is no reliable way to turn this off. Do not read Claude's enthusiasm as validation of your idea or its own output. When you need a genuine critique, ask for it explicitly, or have a *fresh* session review the work — a separate context that didn't produce the work evaluates it more honestly than the one that did. +Be wary of sycophancy. Generative models are trained to be agreeable and positive, and there is no reliable way to turn this off. Do not read Claude's enthusiasm as validation of your idea or its own output. When you need a genuine critique, ask for it explicitly, or have a *fresh* session review the work — a separate context that didn't produce the work evaluates it more honestly than the one that did. Memory can reinforce sycophancy: if Claude records that you prefer agreement, that bias carries into new chats, so even starting fresh may not reset it (see *Memory*). Work securely and responsibly ------------------------------