agentleFS
Sign inStart free
SupabaseKnown publishersupabase/supabase-go/.agents/skills/designing-internal-boundaries/SKILL.md

designing-internal-boundaries

Skill10 starsChanged 44 days agoMITView on GitHub

Guides the design of internal type contracts in respect of immutability and encapsulation. Enhances codebase maintainability by separating concerns in a manner that is compiler-enforced, both for internal state as well as immutable values returned to callers alike. Use when creating or reworking types, when adding machinery (e.g. parsing, caching, transport, crypto), when naming or splitting an internal package, when writing constructors or defensive copies and when deciding whether a test is external or in-package.

The file

We split this skill into the rules it gives an agent

1 rule. About 0 are common, 1 is distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    One concern per package and let naming police that: If no single plain word names the package then it probably covers multiple concerns, …

    line 12

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill 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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

In Go the package is the only compiler-enforced encapsulation boundary. File boundaries are decorative, so any file in a package can assign any unexported field declared anywhere in that package. A contract enforced only by convention is not enforced, causing maintainability issues as the amount of source code in a package increases (whether by line count or file count), so should be considered a design smell.

Exemplars include: postgrest/internal/exchange and the auth/internal packages (token, key, cache, profile, plus testkit for shared fixtures).

Highlights of good design:

  1. One concern per package and let naming police that. If no single plain word names the package then it probably covers multiple concerns, therefore should be split into multiple packages. A coined compound name is usually a design smell.
  2. A contract-carrying type is a one-field wrapper. auth.Claims is struct{ inner token.Claims }: the inner type lives in an internal package and its fields are unexported, so only that package can touch them. Public accessors forward to inner, carrying the consumer-facing docs and no logic. Contract-free types stay ordinary structs (auth.Error keeps exported fields).
  3. Constructors are the only source of values. The internal package exports them, and the public package never builds or mutates inner values. Reassigning inner still compiles - never do it.
  4. Defensive copies live with the fields they protect. Clone maps and slices in the owning package's accessors, never in forwarders. Document shallow clones.
  5. Policy stays public, machinery goes internal. Sentinels, error shaping, routing and fallbacks stay in the public package, while HTTP and credentials are injected as closures - the error model is defined once.
  6. Cross boundaries by value. A shared pointer hands read-only code a mutable alias (the *url.URL lesson).
  7. Tests are external by default. *_test.go files are package x_test. In-package tests live only in *_internal_test.go files, for behavior a boundary genuinely hides. Shared fixtures go in an internal test-support package, never into widened production API.
  8. Know when to stop. Single-function wire carriers and contract-free types need no boundary. Enforce stated contracts, not ceremony.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.

Check your setup, free