GopherForgeA WORKBENCH FOR GO

Around Go: coding agents · 3 MIN READ

Repository guidance for Codex, Claude Code and Cursor

Write useful Go repository instructions without confusing context with permissions.

Durable guidance saves repeated explanation of layout, build commands and boundary rules. The supported discovery mechanisms differ between products and can change. Keep the repository facts stable, then consult the official documentation for how the installed tool discovers and scopes them.

Repository guidance for Codex, Claude Code and Cursor · A MAP OF THE IDEA

  1. Document real commands
  2. Choose tool-specific scope
  3. Check loaded guidance
  4. Enforce tool permissions

Useful when

  • Write useful Go repository instructions without confusing context with permissions.
  • Keep repository facts concrete, scope guidance using each product’s documented mechanism and enforce permissions in the environment. Recheck discovery after tool changes.

Watch out

  • Do not share secret values in instruction files or assume that a context exclusion blocks all tool access.

Implementation & operation cost: Choose the policy from the actual contract, then verify its failure path in the target environment.

01

Write the repository facts once

Describe the real Go module, generated files, focused tests and opt-in integration environment. Use exact working directories and commands. Keep examples free of credentials and name environment variables without values. A new developer should be able to follow the same instructions without an agent.

text
# Go service working agreements
- Supported compiler: follow go.mod and the CI toolchain.
- Unit checks: go test ./...
- Worker changes: go test -race ./internal/worker/...
- Generated API: run the pinned generator documented in docs/generate.md.
- Integration checks use disposable databases; never production endpoints.
- Preserve public error and JSON contracts unless the task changes them.
Read the code

This illustrative guidance belongs in the repository instruction mechanism used by the selected tool. It is not an instruction for GopherForge itself. Replace package paths and generation commands with ones that exist in the actual checkout.

02

Map facts to the tool deliberately

Codex uses AGENTS.md with directory-scoped discovery and override rules. Claude Code uses CLAUDE.md and its documented rules and memory mechanisms. Cursor offers AGENTS.md and project rules in .cursor/rules with selectable scope. Do not assume copying one filename gives identical precedence in every product.

03

Verify the loaded scope

When guidance appears ignored, ask the tool which files it loaded and inspect its documented diagnostics. A nested instruction may override a general rule. Avoid growing one global instruction file into a second copy of the whole codebase; link concise maintained project documents where supported.

04

Keep controls separate from prose

A sentence saying do not access production is useful intent, but it does not revoke a credential. Use actual sandbox, approval and account controls in the environment. A rule file is not an authentication boundary, and ignoring a file for indexing does not necessarily prevent shell tools from reading it.

TAKE THIS WITH YOU

Keep repository facts concrete, scope guidance using each product’s documented mechanism and enforce permissions in the environment. Recheck discovery after tool changes.

Check your understanding

A repository instruction says not to query production, but the shell has a production credential. What provides the actual boundary?

Go to the source

Progress stays in this browser. No account needed.