Index of every page on this site: llms.txt
All skills
erkamyaman avatar

/architecture-for-agents

@7fcc555
Run it yourself

Use when structuring a codebase that AI agents will edit heavily. Weighs duplication against abstraction now that repeating code and keeping copies in sync is cheap.

  • 2 files
  • 2.5 KB
  • Updated 2 months ago
  • GitHub
Use this Skill: https://skilld.dev/gh/erkamyaman/dhh-p-bloom-agent-skills/architecture-for-agents

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈48 tokens for metadata: the name and description. ≈427 when used: this file. ≈167 more on demand in 1 file.

Description uses 2.4% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈191 characters, or 2.4%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Architecture for agents

Inspired by DHH's Rails World 2026 keynote: https://www.youtube.com/watch?v=vDjW_dRyKXY

From the talk

DHH says abstractions make less sense when hundreds or thousands of agents may be changing an app, because the choke points they create get in the way. He also says the cost of repetition and of keeping copies in sync has dropped to near zero, and that no one has the blueprint yet. The decision table and steps below are our additions, not from the talk.

The talk argues that part of the reason for abstractions (not repeating yourself) weakens when agents can change many places quickly, and that shared choke points can slow down many agents working at once. Treat this as a hypothesis to test, not a rule.

When to use

  • Deciding whether to extract a shared helper, base class or service.
  • A codebase is hard for agents to change because everything depends on one module.

Steps

  1. Find the choke points: modules that many features depend on and that change often.
  2. For each, ask: does sharing this code save real effort, or does it only avoid repetition?
  3. Prefer small, clear, self-contained modules with explicit boundaries and good tests.
  4. Allow duplication when copies are small, stable and covered by tests. Keep abstraction where the logic is subtle or must stay consistent (security, money, data rules).
  5. Name things clearly and keep a short architecture note in the repo so agents and people share the same map.

Verification

Pick a typical change and let an agent make it. Count the files it had to touch and the tests that broke. If one shared module caused most of the pain, reconsider it.

See references/duplicate-or-abstract.md.

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at 7fcc555. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub last month.

Activeupdated 2 months ago

README badge

README badge for erkamyaman/dhh-p-bloom-agent-skills/architecture-for-agents