From 2ea73e40a8ecdd7de55ee0f94b524fcd7a1224a4 Mon Sep 17 00:00:00 2001 From: didericis Date: Fri, 29 May 2026 00:40:19 -0400 Subject: [PATCH] =?UTF-8?q?docs(decisions):=20ADR=200003=20=E2=80=94=20sys?= =?UTF-8?q?tem=20prompts=20stay=20user-directed?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Record that we considered auto-generating an agent's system prompt from its bottle's egress/git config (so it would know its access up front) but opted to keep prompts operator-authored: we may want to withhold that information from the agent directly, and the agent can infer its access on its own regardless. Co-Authored-By: Claude Opus 4.8 --- .../0003-system-prompts-stay-user-directed.md | 43 +++++++++++++++++++ 1 file changed, 43 insertions(+) create mode 100644 docs/decisions/0003-system-prompts-stay-user-directed.md diff --git a/docs/decisions/0003-system-prompts-stay-user-directed.md b/docs/decisions/0003-system-prompts-stay-user-directed.md new file mode 100644 index 0000000..191c6ec --- /dev/null +++ b/docs/decisions/0003-system-prompts-stay-user-directed.md @@ -0,0 +1,43 @@ +# ADR 0003: Keep agent system prompts user-directed, not auto-generated from config + +- **Status:** Accepted +- **Date:** 2026-05-29 +- **Deciders:** didericis + +## Context + +A bottle already declares exactly what an agent can reach: egress routes +(allowlisted hosts + auth) and git config (remotes + identity). We +considered deriving an agent's system prompt — or a section of it — +automatically from those configs, so an agent would be told up front +what it has access to (e.g. "you can reach `gitea.dideric.is` over the +git remote and its API"). The question surfaced while hand-writing that +exact line into the `claude-implementer` prompt. + +## Decision + +System prompts stay **user-directed** — authored by the operator. We do +not auto-generate prompt content from a bottle's egress / git config. + +## Consequences + +- The operator controls what the agent is *told* about its environment, + independently of what the bottle *grants*. Sometimes we may want to + withhold that information from the agent directly — keep the prompt + silent about an allowlisted host even though egress permits it. +- The agent can still infer its access on its own (attempt a request, + read its env, `git remote -v`, the gitconfig), so auto-injection is a + convenience, not a capability the agent depends on. +- Cost accepted: operators must restate access in the prompt when they + want the agent to know it (as we did for the Gitea instance), and the + prompt can drift from the config. That decoupling of "what the bottle + grants" from "what the agent is told" is the point. +- Revisit if keeping prompts in sync with configs becomes a real pain. + An *opt-in* helper that emits a capability summary the operator + chooses to include would honor this decision; silent auto-injection + would not. + +## Links + +- ADR 0002 (`0002-agent-identity-claimed-not-vouched.md`) — related + agent-trust posture (what the agent is granted vs. what it can claim). -- 2.52.0