agentleFS
Sign inStart free
PostHogKnown publisherPostHog/posthog-foss/common/AGENTS.md

posthog-foss / common

AGENTS.md727 starsChanged yesterdayMITView on GitHub

common/ is a transitional holding pen, not a destination. It holds shared code that predates a better home. Do not treat it as the default place for new shared code. The name is the smell. A catch-all common/ reliably rots into a junk drawer — unscoped, unenforced, imported by everything — i.e. a second monolith with worse boundaries than the first. Unlike products/* (guarded by tach + turbo), nothing mechanically guards what lands here, so the only thing keeping it…

We split this AGENTS.md into the rules it gives an agent

2 rules. About 0 are common, 0 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    When something here becomes a clean leaf (no back-edges into app code), promote it to packages/ or into the owning product, and delete it …

    line 22
  2. Very specific:

    Keep folder names under_score cased — dashes break Python imports.

    line 26

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

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

common/ — read before adding code here

common/ is a transitional holding pen, not a destination. It holds shared code that predates a better home. Do not treat it as the default place for new shared code.

Disclaimer

The name is the smell. A catch-all common/ reliably rots into a junk drawer — unscoped, unenforced, imported by everything — i.e. a second monolith with worse boundaries than the first. Unlike products/* (guarded by tach + turbo), nothing mechanically guards what lands here, so the only thing keeping it honest is this file. The goal for common/ is to shrink, not grow.

Before adding anything here

Pick a home with a real boundary first, in this order:

  • products/<name>/ — owned by one product
  • tools/ — dev/CI tooling, not shipped at runtime
  • services/ — independently deployed
  • packages/ — a clean, published-style leaf with no back-edges into app code (see packages/quill)

Fall back to common/ only when none of those fit and the code can't yet be a clean leaf because it still imports app modules (lib/*, scenes/*, etc.). If you do, treat it as tracked debt: say so in the PR and name the intended graduation target. "It follows an existing common/ precedent" is not, on its own, a reason to add more.

Graduating out

When something here becomes a clean leaf (no back-edges into app code), promote it to packages/ or into the owning product, and delete it from common/. That is the success path — quill took it.

Conventions

  • Keep folder names under_score cased — dashes break Python imports.
  • Human-facing overview: README.md. Repo-wide layout: monorepo layout.

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.

Reviews can't be read right now.

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