Ucai Patterns

Best practices for working with Claude Code's native architecture. These patterns are derived from how Anthropic builds their own plugins.

Context Management

The context window is a shared resource. Protect it.

Native tools for context:

• SessionStart hooks: Inject project-specific context at session start
• tasks/todo.md: Write progress to tasks/todo.md so hooks can inject state and context compaction doesn't lose your place
• Skills with progressive disclosure: Metadata always loaded, details on demand
• File system: Use .local.md files for persistent state between iterations

Anti-patterns:

• Stuffing CLAUDE.md with framework instructions (use project facts only)
• Repeating information Claude already knows (conventions of popular frameworks, etc.)
• Loading everything upfront instead of on demand

For detailed patterns, see: references/context-management.md

Red Flags — Context Management

Pathological Honesty applies to every Red Flags table in this skill: the "Reality" column states what's wrong with the thought. When you catch yourself in one of these thoughts, name a concrete failure mode you've already seen or can see — a real session that overflowed, a real agent that hung, a real CLAUDE.md that drifted. Abstract realism doesn't change behavior; concrete failure modes do.

Agent Patterns

Agents are focused workers, not personas.

Native agent format: Markdown files with YAML frontmatter declaring name, description, tools, model, and color. Each agent has a specific mission.

Key patterns:

• Spawn 2-3 agents in parallel for independent analysis
• Assign appropriate models (sonnet for exploration, opus for deep bug analysis)
• Restrict tool access to what each agent needs
• Consolidate results in the orchestrating command, not in another agent
• 1 message = ALL agents: Spawn all parallel agents in one message — see Batch Operations below

For detailed patterns, see: references/agent-patterns.md

Red Flags — Agent Patterns

Batch Operations

The golden rule: 1 message = ALL related operations. Every round-trip to Claude adds latency. Batch everything that can go together.

Good patterns:

• Spawn ALL parallel agents in one message (multiple Task calls in one response)
• Read ALL files you need in one message (multiple Read calls simultaneously)
• Batch ALL tasks/todo.md updates in a single Write call, not one per item
• Stage all writes for one phase before moving to the next

Anti-patterns:

• Spawning one agent, waiting for it, then spawning the next
• Reading files one at a time in a loop across multiple messages
• Writing to tasks/todo.md once per todo item across separate turns

Why it matters: In a 5-agent parallel analysis, serial spawning adds 4 unnecessary round-trips. At 2-3 seconds per round-trip, that is 8-12 seconds of pure latency before any work begins. Batching collapses this to a single round-trip.

For detailed patterns, see: references/agent-patterns.md

Red Flags — Batch Operations

Gate — before spawning any agent:

Am I about to launch this agent alone, wait for it, then spawn the next?
→ Yes → STOP. Bundle all agents into one message first.
→ No  → Proceed.

Gate — before any file read:

Do I know other files I'll need in this session?
→ Yes → Read all of them now in this same message.
→ No  → Proceed with current read.

Hook Patterns

Hooks are lifecycle event handlers. They are the primary extension point.

Hook events: SessionStart, PreToolUse, PostToolUse, PostToolUseFailure, Stop, UserPromptSubmit, SubagentStop, SubagentStart, PreCompact, SessionEnd, PermissionRequest

Key patterns:

• SessionStart: Inject project context
• PreToolUse: Guardrails before writes/edits
• Stop: Iteration control (block exit, feed task back)
• Exit code 2 blocks the operation

For detailed patterns, see: references/hook-patterns.md

Red Flags — Hook Patterns

Anti-Patterns

Named mistakes to avoid. Each has a symptom and a fix.

For the full catalogue, see: references/anti-patterns.md

Red Flags — Anti-Patterns

For skill and command authoring principles (persuasion techniques, gate functions, enforcement language), see: references/skill-design-principles.md