clawker
AGENTS.md59 starsChanged 12 days agoMITView on GitHub
Clawker is a Go CLI that runs coding agents in Docker containers with controlled access to host resources. Claude Code and Codex must use the same project instructions, skills, and memories. Store instructions in regular AGENTS.md files. Each must have a sibling CLAUDE.md symbolic link with the relative target AGENTS.md. Before reading or changing files, read the Serena core memory and the memories it names for the touched domain. Read package AGENTS.md files along the path to each file, including…
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository17 other files it gives its agents.
- clawkerd/AGENTS.mdAGENTS.md
- controlplane/AGENTS.mdAGENTS.md
- docs/AGENTS.mdAGENTS.md
- test/AGENTS.mdAGENTS.md
- .github/copilot-instructions.mdCopilot instructions
- agent-filesSkill
- audit-memorySkill
- cli-outputSkill
- dev-checksSkill
- firewall-uatSkill
- initiativeSkill
- monitoring-checksSkill
- store-editorSkill
- test-hunterSkill
- wizard-commandsSkill
- writing-testsSkill
- code-reviewSkill
The file
Show its rules and text
We split this AGENTS.md into the rules it gives an agent
16 rules. About 0 are common, 7 are distinctive, and 9 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈7
Distinctive · estimate
This author's own choices. Worth a look.
9
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 9
Before reading or changing files, read the Serena core memory and the memories it names for the touched domain.
- Distinctive: line 10
Read package AGENTS.md files along the path to each file, including files outside the working directory.
- Very specific: line 11
Use instructions already loaded in the session.
- Very specific: line 12
Keep .agents/ independent of any harness.
- Distinctive: line 19
Consider architecture, tests, documentation, and effects on users and developers.
- Very specific: line 20
Follow the Serena design and architecture memories.
- Distinctive: line 21
Write tests before production code.
- Distinctive: line 22
Update the README, affected AGENTS.md files, documentation, and shared memories after changes.
- Distinctive: line 23
When both agents work at the same time, preserve the other agent's edits and check the current diff before writing shared files.
- Distinctive: line 24
Use ASD-STE100 Simplified Technical English and its current approved dictionary for chat, documentation, and code comments.
- Very specific: line 30
Do not add lint suppressions without explicit user approval.
- Very specific: line 32
When CLAWKER_AGENT is set, never run go test ./...: the e2e suite tears down the host CP.
- Very specific: line 45
Use unique agent names with random suffixes.
- Very specific: line 46
Never discard errors; log cleanup failures with t.Logf.
- Distinctive: line 48
Add no production code only to serve a test seam.
- Very specific: line 68
Update the affected memories before completing work.
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Clawker
Clawker is a Go CLI that runs coding agents in Docker containers with controlled access to host resources.
Shared instructions
Claude Code and Codex must use the same project instructions, skills, and memories.
Store instructions in regular AGENTS.md files. Each must have a sibling CLAUDE.md symbolic link with the relative target AGENTS.md.
Before reading or changing files, read the Serena core memory and the memories it names for the touched domain.
Read package AGENTS.md files along the path to each file, including files outside the working directory. Requirements for one package tree live in that tree's AGENTS.md.
Use instructions already loaded in the session. Do not load an entire reference directory.
Keep .agents/ independent of any harness. Store native settings and tool-specific hooks in .claude/ or .codex/. A skill that is also a subagent keeps each harness definition in its agents/ directory.
Work rules
- State assumptions. Present different interpretations and ask when the choice is unclear.
- Define a verifiable result before coding. For work with multiple steps, state a short plan and its checks.
- This is an alpha project. Correct design defects and technical debt before continuing affected work.
- Consider architecture, tests, documentation, and effects on users and developers. Use a simpler design when possible.
- Follow the Serena
designandarchitecturememories; update them when the design changes. - Write tests before production code. Add missing interfaces, mocks, fakes, and test subpackages as required. All applicable tests must pass.
- Update the README, affected
AGENTS.mdfiles, documentation, and shared memories after changes. - When both agents work at the same time, preserve the other agent's edits and check the current diff before writing shared files.
- Use ASD-STE100 Simplified Technical English and its current approved dictionary for chat, documentation, and code comments. Replace unapproved words unless they are standard technical names. Apply the standard; do not restate it.
Critical rules
- The control plane (CP) runs whenever managed agent containers exist. Only its firewall subsystem is optional. Never gate other CP behavior on
firewall.enable. - A CP crash leaves pinned eBPF state without supervision. Before changing CP startup, serving, or their dependencies, read control-plane safety.
- Do not add lint suppressions without explicit user approval. See the Serena
conventionsmemory for errors, constants, and context rules. - Pin external dependencies to exact versions with integrity verification. See the dev-checks skill.
- When
CLAWKER_AGENTis set, never rungo test ./...: the e2e suite tears down the host CP. Use targeted packages ormake test.
Dependency placement
- Implementation lives in
internal/<package>/, never incmdutil/.cmdutil/holds only the Factory struct, output utilities, and argument validators. - The only question is who constructs a dependency. Constructed at startup and used by three or more commands: a Factory field. Constructed at startup for fewer commands: the command imports the package and holds it on its Options struct. Needs CLI arguments or runtime context: constructed in the run function, tested by injecting a mock on Options.
- Package ownership: Serena
architecturememory, Key Packages and Package Import DAG.
Testing rules
- Docker is always available. Never defer or skip Docker-based tests. When a change touches containers, networks, or volumes, write the integration test in the same task.
- Unit tests are co-located
*_test.gofiles without Docker.test/e2e/needs Docker;test/whail/needs Docker and BuildKit. No build tags; directory separation only. Name testsTestFunctionName,TestFeature_Integration, orTestFeature_E2E. - Each package in the dependency DAG provides its own test utilities. If a node lacks them, add them first.
- Use unique agent names with random suffixes. Stop containers before removing them. Register cleanup with
t.Cleanup()and usecontext.Background()inside it. Intest/whail/, gate Docker tests withrequireDocker(t)(test/whail/helpers_test.go). Thetest/e2e/harness has no Docker gate: it fails the test when Docker calls fail. - Never discard errors; log cleanup failures with
t.Logf. - Co-located
*_test.gofiles never importtest/e2e/harness. Never callfactory.New()outsideinternal/clawkercmd/cmd.go; build&cmdutil.Factory{}literals with test doubles. - Add no production code only to serve a test seam. Test doubles adapt to production, not the reverse.
- Helpers, fixtures, tiers, and examples: writing-tests skill.
Commands and references
- Build CLI:
go build -o bin/clawker ./cmd/clawker - Unit tests without Docker:
make test - Build, integration tests, embeds, hooks, and completion checks: dev-checks skill.
- CLI, config, naming, package boundaries, and terminal behavior: Serena
project-guidememory. - Package dependency and layering questions: run
go list -deps ./<pkg>orgo list -f '{{.ImportPath}} {{.Imports}}' ./...and answer from that output. - Agent file layout and native tool settings: agent-files skill.
- Shared skills:
.agents/skills/. EachSKILL.mddescription names its trigger; invoke the matching one. Behavioral and situational guidance is a skill, not a memory.
Project knowledge: Serena memory bank
Project knowledge lives in the Serena memory bank at .serena/memories/: plain Markdown files, one topic per file, with / in a name as a topic folder (cli/core). Memories reference each other as `mem:<name>`. Nothing injects memory content; you read what the names and references make relevant.
- Initialize Serena with
initial_instructions, thencheck_onboarding_performedif available, thenlist_memories. Readcorefirst: it is the graph root and names a memory for each work area with what that memory covers. Follow itsmem:references for the domain you touch. If Serena is absent, read the same files under.serena/memories/. - System knowledge:
architecture(layers, Factory dependency injection, package DAG, key packages),design(philosophy, concepts, security model, lifecycle),key-concepts(types and terms),repo-structure(directory map),project-guide(CLI surface, config schema, design decisions, terminal gotchas),conventions(errors, logging, constants, context, output),tech_stack(build inputs and pins), and a<domain>/coreper work area. - Retained records:
plans/core,tracking/core,research/core,history/core,security/core. Dated; check source before reusing a claim. - Update the affected memories before completing work. Follow
memory_maintenancefor placement, naming, and links, and runserena memories checkwhen the CLI is available. Behavioral and situational guidance is a skill in.agents/skills/, not a memory. - For GitHub repository documentation, try DeepWiki
ask_question, then Context7, then other documentation tools. For library APIs, resolve the Context7 library ID before requesting its documentation.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

