diff --git a/agents/AGENTS-claude.md b/agents/AGENTS-claude.md index 00f11d8..74e6b8d 100644 --- a/agents/AGENTS-claude.md +++ b/agents/AGENTS-claude.md @@ -2,12 +2,9 @@ ## Company knowledge (onyx & thicket) -- **Onyx (skill) is the default for any company-knowledge question** — - processes, products, services, systems, teams, ownership, "wie - machen wir X bei Seibert". Its semantic index surfaces pages that - direct CQL/JQL search misses, and `answer` (the default mode) also - reaches org data via Thicket/Sourcebot/HubSpot. Use `search` only - when you need the source text itself. Always cite source links. +- Company-knowledge questions go to the `onyx` skill first (its description + says when); its index surfaces pages that direct CQL/JQL misses. Always cite + source links. - Two shortcuts past onyx: Thicket MCP for people lookups (role, team, email — its other sections are thin), Confluence CQL for precise lookups with known space/title. diff --git a/agents/AGENTS.md b/agents/AGENTS.md index 0fcdae9..c3447af 100644 --- a/agents/AGENTS.md +++ b/agents/AGENTS.md @@ -54,87 +54,49 @@ Treat vague input and question-back responses critically, not as instructions. cognee is a real memory, not an archive: unlike `MEMORY.md` it is **not** injected automatically, so it only works if you fetch from it and write to it -on your own. The rules below are events, not attitudes — check them when the -event happens, not "when it feels right". +on your own. Command forms, flags, dataset sharing and failure modes are in the +`cognee` plugin skill; this section only says *when*. -### Read: `recall` before you start - -Run `recall` **before the first tool call**, not after you are already deep in -the task, when any of these is true: - -- the task touches infrastructure, a server, a service, a ticket or a tool - we run ourselves -- an error looks like it could have happened before ("this smells familiar") -- you are about to pick between options where a decision may already exist -- the task will plausibly take more than a handful of tool calls - -`recall ` — no flags. It reads every readable dataset including the -team one. `--team` exists on `remember` only; on `recall` it is a usage error, -and `--dataset team-it` fails too because the team dataset is shared rather -than owned (it would need its UUID). Neither is needed: plain `recall` covers -everything. - -Treat what comes back like a colleague's note: useful, possibly outdated. If a -memory names a file, flag or host, verify it still exists before acting on it. - -### Write: `remember` at these moments - -Announce it in one line, never ask first. Write **as the insight appears**, not -at the end of the session — by then the detail that made it worth saving is -gone. - -- a bug is fixed and the cause was **not** visible in the code (config, - limits, environment, an API that lies) -- a decision is made and an alternative was rejected — save the *why*, that is - what the code cannot tell later -- a measurement contradicts an assumption, mine or yours -- you correct me, or I correct myself after being wrong -- a tool, API or service behaves differently than its docs claim - -What does **not** belong there: anything the repo already records, anything -that only matters inside this one conversation, and never secrets, -credentials or customer-personal data. - -### Routing and hygiene - -- **Team bucket** (`remember --team`): everything concerning team IT — Seibert - IT-Infra, ISAC/bw, monitoring, INFRA board, shared services, servers, team - processes. Ask yourself: would a colleague hitting this next month benefit? -- **Personal dataset** (plain `remember`): my preferences, workflow feedback, - context that is only relevant to me. -- On recurring topics `recall` first and **extend the existing note instead of - adding a second one** — two notes on one topic are worse than none, because - the older one keeps surfacing. -- Write notes that answer a question, not headlines. Include the concrete - numbers, the error message verbatim, and the fix. A note that says "there - was a problem with X" costs more time than it saves. -- No need to economize on characters: cognee has no size limit, so write - notes comprehensively and self-contained. -- Always keep the external references and source links in the note — they - matter: Confluence, Jira, TeamVault, and, for notes that grew out of a Google - Chat discussion, the source-thread URLs - (`https://chat.google.com/room//`, for individual - messages append the ``) so the original discussion stays - traceable — not just a separate index. +- **Read: `cognee recall ` before the first tool call** when the task + touches infrastructure, a server, a service, a ticket or a tool we run + ourselves; when an error "smells familiar"; when choosing between options + where a decision may already exist; or when the task will plausibly take more + than a handful of tool calls. Plain `recall` reads every readable dataset, + team included. Treat what comes back like a colleague's note: useful, possibly + outdated; verify a named file, flag or host still exists before acting on it. +- **Write: `cognee remember` as the insight appears**, not at session end. + Announce it in one line, never ask first: memory writes are exempt from any + project rule that asks to confirm write actions (those rules target external + systems: Jira, chat, Confluence, hosts). Moments: a bug fixed whose cause was + not visible in the code; a decision with a rejected alternative (save the + *why*); a measurement that contradicts an assumption; a correction, yours or + mine; a tool or API that behaves differently than its docs claim. +- **Routing:** `--team` for everything concerning team IT (Seibert IT-Infra, + ISAC/bw, monitoring, INFRA board, shared services, team processes), plain + `remember` for my preferences and personal context. Never secrets, + credentials or customer-personal data; nothing the repo already records; + nothing that only matters inside this conversation. +- **Projects with their own findings convention** (task folders, + `erkenntnisse/`, `decisions/`): write the file there first, then the cognee + note with the conclusion and a link to the file. The file is the detailed + record; cognee is what the next session or a colleague in another repo finds. +- **Hygiene:** on recurring topics `recall` first and extend the existing note + instead of adding a second one. Write notes that answer a question: concrete + numbers, the error message verbatim, the fix, and the external references + (Confluence, Jira, TeamVault, Google Chat thread URLs + `https://chat.google.com/room//`). No size limit, so + write self-contained. ## Sandbox -- **Always run commands sandboxed first.** Only use `dangerouslyDisableSandbox: true` as a last resort after a sandbox-related failure — never preemptively. +- **Always run commands sandboxed first.** Only use `dangerouslyDisableSandbox: true` after a sandbox-related failure — never preemptively. One targeted retry with the identified cause fixed is fine; retrying in a loop is not. - **On sandbox failure:** analyze the error message for the blocked path, then suggest adding it to `sandbox.filesystem.allowWrite` in `~/.claude/settings.json`. Only fall back to `dangerouslyDisableSandbox: true` if the path can't be determined or the user prefers it. - **Commands that must run unsandboxed belong in `sandbox.excludedCommands`** (e.g. `git *`, the pinned `bin/srv`-style wrappers), not behind the flag: the exclusion is the owner's decision, the flag is the model's. Without a hook, the flag is only a convention: an unsandboxed command that matches an allow rule (`Bash(git *)`, `Bash(pytest *)` …) runs without a prompt in default mode, and auto mode may wave it - through as well. -- **Removed hook (2026-10-04, kept here for reference).** Until then a `PreToolUse` hook on `Bash` in - `~/.claude/settings.json` intercepted every call with `dangerouslyDisableSandbox: true` and forced a - permission prompt (`ask`); it was removed because an unattended overnight session would hang on that - prompt until morning. To reinstate it, add under `hooks.PreToolUse` (use `"deny"` instead of `"ask"` for - a hard block without a prompt): - ```json - {"matcher": "Bash", "hooks": [{"type": "command", "statusMessage": "Checking sandbox bypass...", - "command": "jq -e '.tool_input.dangerouslyDisableSandbox == true' > /dev/null 2>&1 && printf '{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"ask\",\"permissionDecisionReason\":\"Sandbox bypass requested. Retry with dangerouslyDisableSandbox omitted; set it only after a confirmed sandbox-caused failure.\"}}' || true"}]} - ``` + through as well. (The former PreToolUse hook that forced a prompt on the flag was removed 2026-10-04; + its JSON is in this file's git history.) ## Temporary Files @@ -171,34 +133,18 @@ credentials or customer-personal data. checkout stays first choice when it exists. Never call `ask_codebase` on your own — it spawns a nested server-side agent (minutes per call, shared vLLM); use it only when explicitly asked. -- **`ccc` for semantic code search.** Repos containing a - `.cocoindex_code/` directory are indexed by - [`ccc`](https://github.com/cocoindex-io/cocoindex-code). Reach for - it on conceptual questions ("where is X used / which files do Y / - what handles Z"), where a keyword grep would miss indirect usage: - `ccc search ''`. Results are filtered to the current working - directory's subtree, so **run the search from the project root** — that is - the cheap way to see everything. `--path '**'` achieves the same from a - subdirectory, but from the root it is a no-op *and* about three times - slower (measured 2026-09-02 on a 1005-file index: 0.35 s against 0.12 s, - identical hits), so pass it only when you cannot control the cwd. - **Embeddings only, no keyword component:** searching an exact string - (a UUID, a ticket ID, an error message) does not return the file that - contains it — verified. `grep`/`rg`/`find` own exact-string lookups. - A low score is a warning, not a hit. The `ccc` skill has the full - reference. -- **`ccc index` / `ccc init` are read-safe maintenance.** They only - write to the gitignored `.cocoindex_code/` directory, never to - source. Run them without confirmation prompts — at session start, - after refactors, or before a search when the index may be stale. - Treat like `grep` for permission purposes, not like a code edit. -- **`md` für lange Markdown-Dateien statt `head`/`grep -n '^#'`.** - `md outline ` gibt den Überschriftenbaum mit Zeilennummer und - Größe pro Abschnitt (`[164 Zeilen, ~2.1k Tok]`) — daraus die - Lese-Entscheidung treffen, dann `md section "<Überschrift>"` - für genau diesen Teilbaum (Query auch als Slug oder `L48`; `--range` - liefert `offset limit` fürs Read-Tool, `--depth 0` schneidet - Unterabschnitte ab). Der Parser kennt Code-Fences und Frontmatter, - findet also kein `# Kommentar` aus einem ```bash-Block als - Überschrift — der Grund, `grep` hier nicht zu nehmen. Bei Dateien - unter ~500 Zeilen direkt `Read`, der Umweg lohnt erst darüber. +- **`ccc` for semantic code search.** Repos containing a `.cocoindex_code/` + directory are indexed by `ccc`. Reach for it on conceptual questions ("where + is X used / what handles Z"), where a keyword grep would miss indirect usage: + `ccc search ''` from the project root. It is embeddings only: exact + strings (UUIDs, ticket IDs, error messages) stay with `grep`/`rg`. Details and + gotchas in the `ccc` skill. +- **`ccc index` / `ccc init` are read-safe maintenance.** They only write to the + gitignored `.cocoindex_code/` directory, never to source. Run them without + confirmation prompts; treat like `grep` for permission purposes. +- **`md` for long Markdown files instead of `head`/`grep -n '^#'`.** + `md outline ` prints the heading tree with line numbers and size per + section; decide from that, then `md section ""` for exactly + that subtree (`--range` yields `offset limit` for the Read tool, `--depth 0` + cuts subsections). It knows code fences and frontmatter, so a `# comment` in + a bash block is not a heading. Below ~500 lines just `Read` the file.