CHAPTERS
Why PMs must scale: supporting bigger, cross-functional teams with AI
Aakash frames the trend: PMs increasingly support 10–20+ partners across engineering, design, data, and go-to-market. Hannah explains how roles are blending (PMs doing analysis/prototyping; engineers/designers making product decisions), making shared context the bottleneck—and the leverage point.
- •PM scope is expanding in headcount and functions (sales/marketing/support in the loop)
- •Roles are converging: more product decision-making distributed across the team
- •AI changes the shape of work, but context becomes the limiting factor
- •Need a system that lets everyone access consistent, high-quality context quickly
Team OS: the shared knowledge repo that turns context into leverage
Hannah introduces “Team OS” (Team Operating System): a single repository that holds a team’s shared context and workflows. She outlines the core structure: a root CLAUDE.md, a .claude folder for shared AI assets, and function-oriented folders for product and team artifacts.
- •Team OS = team-wide knowledge base optimized for AI agents
- •Three-part structure: .claude (agents/skills/commands), product development, team docs
- •Root CLAUDE.md serves as the top-level navigation + operating instructions
- •Goal: faster onboarding, better cross-functional alignment, less repeated explanation
Root CLAUDE.md best practices: keep it lean and action-ready
They unpack what belongs in the root CLAUDE.md and what doesn’t. Hannah emphasizes that root instructions should be minimal, high-frequency context, enabling natural-language actions like messaging the right people via Slack integrations.
- •Root CLAUDE.md should be “very lean,” especially for team repos
- •Include a doc index so the agent knows where to look for information
- •Include team roster + handles and key Slack channels for agentic actions
- •Enables prompts like “Slack Alex…” without re-explaining who Alex is
Context management 101: windows, compaction, and ‘thinking room’
Hannah explains the theory behind the repo design: managing what the model sees, when. She defines context, context window, compaction (lossy compression when full), and thinking room (space left to reason), tying these concepts to performance and reliability.
- •Context = information available to the LLM in a session
- •Context window limits total info; teams produce more than any window can hold
- •Compaction compresses history but reduces fidelity and usefulness
- •Thinking room shrinks as you stuff more context in—hurting reasoning quality
- •Repo structure aims to load only the right context at the right time
Nested CLAUDE.md doc indexes: how Claude navigates without wasting tokens
They show how CLAUDE.md files exist at multiple folder levels as “doc indexes,” letting Claude traverse directly to relevant files instead of exploring the whole repository. Live examples demonstrate low context usage while answering customer questions accurately.
- •Nested CLAUDE.md files describe folder purpose + where key docs live
- •Doc indexes reduce the need for expensive ‘explore/search’ behavior
- •Example query: “Who are my top customers?” loads only relevant customer files
- •Minimizing irrelevant reads preserves tokens and improves answer quality
Customer intelligence at scale: summaries, per-customer context, and consistent formats
Hannah demonstrates how storing customer data in structured files enables fast synthesis like “Who did I meet in the last two weeks and what did I learn?” The system prioritizes summaries over raw transcripts and uses shared ‘skills’ to standardize outputs across many contributors.
- •Per-customer folders can have their own CLAUDE.md for high-frequency context
- •Claude reads summaries first; drills into transcripts only if needed
- •Shared ‘skills’ enforce consistent customer-call summary templates
- •Consistency enables cross-customer synthesis even across many interviewers
- •Structured storage turns natural language questions into reliable analysis
Shared skills, commands, and workflows: turning team habits into reusable AI primitives
Hannah explains how teams codify repeatable work into shared skills/commands and multi-step workflows stored alongside docs. This creates compounding leverage: everyone captures information the same way, and Claude can execute recurring processes quickly and predictably.
- •Skills/commands standardize how work is done (e.g., summaries, doc formats)
- •Workflows store multi-step processes with execution instructions
- •Enables repeatable meeting/report generation and multi-source synthesis
- •Reduces variability across roles and improves agent reliability
- •Transforms tribal knowledge into reusable, team-owned assets
Scaling analytics with a repo: metrics, queries, schemas, and verified playbooks
They walk through an analytics folder pattern: dashboards, experiment results, investigations, plus the critical triad—metrics definitions, SQL queries, and table schemas. This empowers PMs and engineers to do correct analysis without guessing joins or definitions, reducing hallucinations and errors.
- •Organize analytics by topic/product area with dashboards + investigations
- •Separate: metric definitions vs SQL queries vs table schemas (context efficiency)
- •Live query example: ask for metric definition + SQL + schema in one request
- •Verified playbooks reduce hallucinations by grounding in audited team artifacts
- •Data scientist/analyst can ‘own’ the folder but team benefits broadly
Engineering + operations in the same system: bugs, RFCs, and shared ownership
Hannah argues Team OS is not just for PMs or engineers—everyone contributes, including ops and strategy partners. Bug investigations and RFCs become searchable institutional memory, and functional leads guide structure while the whole team maintains quality.
- •Engineering folder examples: RFCs and bug investigation writeups
- •Bug histories speed up future debugging and agent-assisted investigations
- •Repository is a team asset; functional leads shape conventions
- •Non-technical partners can learn GitHub flows and contribute via PRs
- •AI-native teams treat shared context as a core performance driver
Automations on top of the repo: weekly synthesis, Slack updates, and process glue
They describe “shared automations” as the third pillar: using the repository as the source of truth to produce recurring outputs automatically. Example: a weekly customer research synthesis posted to Slack so the team stays continuously aligned.
- •Automations run on repo contents (e.g., weekly research rollups)
- •Outputs can be pushed into Slack channels automatically
- •Turns ongoing documentation into continuous team awareness
- •Reduces manual coordination overhead and context drift
- •Extends leverage beyond interactive prompting into scheduled workflows
How work gets done day-to-day: docs in Claude, PRs in GitHub, Slack notifications
Hannah describes the tactical operating model: write docs in Claude Code, check them into the repo, and review via pull requests—across PM, design, engineering, data, and ops. Claude can even open PRs and message reviewers via integrated tools and shared commands.
- •“Write every doc in Claude first,” then check into the shared repo
- •Use branches/commits/PRs for reviewable collaboration on context artifacts
- •Claude can create PRs, tag reviewers, and post structured Slack updates
- •Keep PRs scoped for reviewability; split work by reviewer/function
- •GitHub becomes the workflow backbone for non-code product artifacts too
Plan mode for better docs: from basic prompts to robust, verifiable plans
Hannah demonstrates the difference between prompting and planning, using Plan mode to remove the model’s bias-for-action and produce a structured approach. She covers clearing context between tasks, adding verification criteria, checkpointing phases, and explicitly invoking writing guides/skills for consistency.
- •Clear/wipe context when switching tasks to avoid cross-task contamination
- •Basic prompting is unpredictable; planning aligns outputs and reduces rework
- •Plan mode: forces planning first, supports parallel research + repo reading
- •Add verification (citations/URLs, self-check loops) to ensure quality
- •Define phases + checkpoints before drafting; explicitly include writing guides/skills
Parallel agents + long-doc execution: prompts, temp files, and orchestration
They discuss using parallel sub-agents to research and draft different sections, then orchestrating synthesis—critical for long documents given context constraints. Hannah highlights two advanced tactics: inspecting agent prompts and forcing outputs into temporary files to prevent context overload/crashes.
- •Parallelize research/writing across agents to handle long, complex docs
- •Ask Claude to show the prompts it will give sub-agents (alignment control)
- •Ensure sub-agents get the right context files and writing guide
- •Have agents write to temp files; orchestrator compiles to avoid context crashes
- •Track phases so work can resume cleanly after compaction or multi-day runs
The learning flywheel: beginner mindset, avoiding ‘give up early,’ and choosing tools
Hannah and Aakash close with a learning philosophy: keep asking why setups work, iterate daily, and don’t abandon the process after a bad first try. They cover what’s under-hyped (curiosity, depth), when to use chat vs coding agents, and how to create learning time by automating work.
- •Biggest mistake: giving up too early—mastery takes sustained iteration
- •Use Claude to explain and critique your setup to learn the ‘why’
- •Under-hyped: follow curiosity; go deep in one area vs shallow everywhere
- •Tool choice: chat for quick low-context answers; agents for advanced PM work
- •If you have 2 hours, automate something to free 6 hours next week for learning
