Skip to module content
🧠AI Academy
0/91
Sign in
Module 02 Β· ~10 min

Claude Code as the Agency OS

It's a general agent harness that happens to ship with coding defaults.

Reading progress
0/8 Β· 0%

The big idea

πŸ’‘Key idea
The name is misleading. Claude Code isn't a coding tool β€” it's a general-purpose agent harness that happens to ship with coding defaults. Think of it as a command center that can operate any workflow involving files, APIs, and structured tasks β€” including marketing, ops, and client delivery. It has four properties that no off-the-shelf SaaS tool can match: 1. **File-system native** β€” it reads and writes real files in your project folders, not just chat windows. 2. **Extensible in three registers** β€” deterministic hooks (always run, guaranteed), probabilistic skills and CLAUDE.md instructions (the model applies them by judgment), and isolated subagents (separate context, restricted tool access). 3. **MCP-connected** β€” it can talk to any MCP server in your stack. 4. **Headless-capable** β€” it can run on a schedule, triggered by GitHub Actions or an SDK scheduler, with no one watching. Marketing is just another domain of files, APIs, and workflows. That's the reframe.
Quick check
1 question Β· instant feedback
0/1
  1. Which extension mechanism is deterministic?

Numbers that matter

94kβ˜…
Superpowers framework stars β€” the phase-gate pattern that made it viral.
GitHub, obra/superpowers
4
Properties of Claude Code no marketing SaaS has: file-system native, tri-register extensible, MCP-connected, headless.
3
Registers of extension: deterministic hooks, probabilistic skills, isolated subagents.
Quick check
1 question Β· instant feedback
0/1
  1. Why isolate a subagent for a 200-page PDF?

Deep dive

4/4 open

**CLAUDE.md** is the per-project constitution. It sets the rules, tone, client context, and guardrails for every session in that project. It lives in the repo and is versioned in git β€” treat it like code.

**Skills** are auto-discovered from `.claude/skills/` (project-level) or `~/.claude/skills/` (global). The model reads the short header and decides when to load the full instructions.

**Subagents** spin up a separate context window with their own tool allowlist. Use them for role-based orchestration (Strategist delegates to Copywriter) or for context isolation β€” for example, reading a 200-page PDF in a subagent and returning only the synthesis to the main thread.

**Hooks** are deterministic scripts that fire at defined lifecycle events (before a write, after a tool call, etc.). This is how guardrails become guaranteed instead of merely hoped-for.

**Slash commands** are parameterized shortcuts a human triggers β€” `/weekly-report {client}` kicks off the full pipeline with one command.

**Plugins** bundle skills + hooks + MCP configs into a single installable package β€” the distribution format for a future GMS OS offering.

The most-starred Claude Code frameworks all enforce phases instead of letting the agent free-associate.

The Superpowers framework (~94k GitHub stars) uses: Brainstorm β†’ Spec β†’ Plan β†’ TDD β†’ Subagent Development β†’ Review β†’ Finalize. It even deletes code written before tests exist, forcing spec-before-build at a structural level.

Translate the shape to agency work: **Discover β†’ Map β†’ Spec (client-approved) β†’ Build β†’ Verify β†’ Ship.**

The sales asset here is showing a client that your agent *refuses to skip the spec phase*. That's a trust signal most competitors can't match.

**Headless** means Claude Code runs without you present β€” triggered by a schedule or an event.

`claude-code-action` connects Claude Code to GitHub Actions. Use it for nightly content QA, scheduled report generation, or auto-triage of inbound briefs.

The **Agent SDK** lets you write scheduler code that runs cron-triggered agents β€” daily loops for ad-performance pulls, anomaly detection, or Slack briefs with approval gates before anything is sent.

One rule applies to every headless run, no exceptions: **write a structured audit log.** What ran, what it read, what it changed, and what it cost. This is your dispute insurance and the raw material for the client review loop.

Think of the three registers as three levels of certainty:

**Deterministic (hooks)** β€” always fire at defined lifecycle points regardless of what the model wants to do. Use these for safety rules, PII scanning, audit logging.

**Probabilistic (skills + CLAUDE.md)** β€” the model chooses when to apply these. Great for capabilities and conventions, not guarantees.

**Isolated (subagents)** β€” a fully separate context with its own restricted tool set. Great for role-based workflows or keeping big documents from polluting the main context.

AnthropicΚΌs 'Steering Claude Code' engineering post formalizes this as the decision framework for choosing which register to use when designing an extension.

Quick check
1 question Β· instant feedback
0/1
  1. The audit-log rule for headless runs is:

How to run it

  1. One CLAUDE.md per client
    Generated from a template, versioned, never shared across clients.
  2. Hooks over prompts for safety
    Any 'never do X' rule that matters must be enforced deterministically.
  3. Subagent role library
    Strategist, Copywriter, Analyst, Fact-Checker, Brand-Voice Reviewer β€” each with tool allowlist.
  4. Audit log on every headless run
    What ran, what it read, what it changed, cost β€” dispute insurance + review-loop raw material.
Quick check
1 question Β· instant feedback
0/1
  1. The Superpowers framework's cultural rule is:

In the field

πŸ”¬Worked example
CLAUDE.md as per-project constitution: conventions, client context, tone rules, guardrails. Subagents on the Garry Tan pattern (CEO/Designer/EM/Release/Doc/QA) translated to agency roles (Strategist, Copywriter, Analyst, Fact-Checker, Brand-Voice Reviewer). Hooks that block writes outside the client folder, run PII scans before email, append every ad-platform mutation to an audit log.
🚫When not to reach for it
For thinking, drafting, and live client-facing analysis, stay in Claude.ai/Cowork. Don't force the terminal on client conversations. And don't reach for Claude Code when a three-node n8n workflow is the honest answer.
Quick check
1 question Β· instant feedback
0/1
  1. One CLAUDE.md per client, not one global, because:

Pitfalls & takeaways

Failure modes

  • Freeform long chats that drift β€” no phase gates.
  • Enforcing safety only in prompts when a deterministic hook is available.
  • One CLAUDE.md across clients β€” client A's conventions leak into client B's sessions.
  • Headless runs without an audit log.

Durable takeaways

  • Treat Claude Code as a general-purpose agentic shell, not a coding tool.
  • Guardrails belong in hooks, not in prompts.
  • Phase-enforcing workflows beat freeform chat every time.
  • Every headless run writes an append-only audit log.
  • Client-specific configs stay in client repos β€” never global.

Do the work

πŸ‹οΈProve you learned it

Stand up a client repo skeleton: write CLAUDE.md (tone, conventions, guardrails), define one subagent (research analyst), one hook (block writes outside /clients/{name}/), and one slash command (/weekly-report {client}). Run one loop end-to-end and screenshot the audit log.

0 chars
πŸ“¦Artifact to produce
Client repo template: CLAUDE.md, .claude/skills/, .claude/hooks/, subagent roles, slash commands, MCP config.

Sources

  • Β· GMS Field Manual Β§2 (Claude Code as the Agency OS)
  • Β· Anthropic 'Steering Claude Code' engineering post
  • Β· obra/superpowers repository