Agent Prompting Best Practices

Benchmarked against: Anthropic — Prompting best practices Scope: How to configure and prompt SuperPortia agents effectively Key files: CLAUDE.md, .claude/rules/, .claude/skills/

SuperPortia agents are not chatbots — they are autonomous team members with specific roles, rules, and tools. Effective prompting means configuring the right context layers, not writing perfect single prompts.

---

Progressive Disclosure (PD)

Agent prompting in SuperPortia uses a 3-layer loading strategy:

Layer	File	Loading	Purpose
L1	CLAUDE.md	Always loaded	Identity, boot sequence, minimal config
L2	.claude/rules/*.md	Always loaded	Behavioral rules (constitution, cost awareness, tech freshness)
L3	.claude/skills/*/	On demand	Task-specific SOPs, loaded only when needed

Why Progressive Disclosure?

Agent context windows have finite capacity. Loading everything at once wastes tokens and dilutes attention:

Approach	Tokens at boot	Problem
Monolithic prompt	~15,000+	Information overload, agents ignore details
PD 3-layer	~3,000 (L1+L2)	Only what's needed is loaded

L3 skills are loaded only when a specific task matches — a 66s review skill isn't loaded unless the agent is doing a review.

---

CLAUDE.md — the identity layer

CLAUDE.md is the most important file. It defines:

1. Identity — who the agent is, who the Captain is
2. Watch Rule — mandatory timestamp on every reply
3. Boot Sequence — what to do when a new session starts
4. Pre-Flight Check — 3D risk scoring before non-trivial tasks
5. Information Retrieval flow — search UB → delegate search → ingest results
6. Terminology pointer — link to glossary for unfamiliar terms

Design principles for CLAUDE.md

Principle	Detail
Minimal	Only essentials. Everything else goes to L2 or L3
Behavioral	Defines how the agent acts, not what it knows
Pointers, not content	Links to full specs in UB or rules files
No hardcoded dates	Use "current version", not "v1.2 released 2026-03-01"

---

Rules — the behavioral layer

Rules in .claude/rules/ define mandatory behaviors that apply to every session:

Rule file	What it enforces
company-constitution.md	14 supreme articles — knowledge to UB, WO channel, HITL boundaries
agent-intelligence-protocol.md	8 protocols — session start, pre-decision, correction capture
cost-awareness.md	Opus token discipline — delegate what can be delegated
tech-freshness.md	Perishable knowledge defense — verify before using
ub-governance.md	Ingestion rules — English, tags, quality checklist
gsta-alignment.md	Strategic alignment — every report connects to GSTA
compaction-recovery-protocol.md	Memory cliff defense — what to do after context compaction
glossary.md	Term navigation — unfamiliar term → definition + link

Writing effective rules

Do	Don't
Define triggers — "When X happens, do Y"	Write vague aspirations — "Try to be helpful"
Include consequences — "Violation = work incident"	Write suggestions — "Consider checking UB"
Provide links to full specs	Duplicate content from other rules
Keep under 60 lines per rule file	Write encyclopedic rule files

---

Skills — the task layer

Skills in .claude/skills/ are loaded on demand when a specific task matches:

Skill	Trigger	What it provides
66s-review	Major decisions, specs, plans	Six Hats + Six Shoes systematic review framework
hitl-decision-format	Presenting choices to Captain	Structured Q / Options / Recommendation template
create	New project scaffolding	Project structure templates
orchestrator	Multi-agent coordination	Communication scripts

Writing effective skills

# Skill: [name]
## Trigger: When to load this skill
## Steps: Numbered procedure
## Output: Expected deliverable format
## Quality criteria: How to know if it's done well

---

Prompt engineering patterns

1. Research-Before-Plan

Never let agents plan with stale training knowledge:

Agent receives task
    ↓ Classify knowledge needed: Timeless or Perishable?
    ↓ Perishable → search UB → stale? → delegate search → ingest → THEN plan
    ↓ Timeless → use directly

See Research-Before-Plan for full protocol.

2. Pre-Decision UB check

Before any important decision, search for precedents:

search_brain("decision <keyword>")
# Found → report precedent before deciding
# Not found → proceed, note "no UB precedent"

This prevents re-debating resolved decisions.

3. Correction capture (dual-write)

When Captain corrects an agent:

# 1. Personal memory (Memory MCP)
# CORRECTION: [what was wrong] → [what's correct]

# 2. Team memory (UB)
ingest_fragment(
    path="CORRECTION: [description]",
    input_type="text",
    tags="correction,[project]"
)

Both writes are mandatory — personal memory alone means other agents can't see it.

4. HITL decision format

When presenting choices to Captain:

Q: Which engine should we use for intel analysis?
A) Groq — Free, fast, but prone to hallucination on important tasks
B) Gemini — $0.014/search, authoritative with citations
C) DeepSeek — Very cheap, good reasoning, no web search
Recommendation: B (Gemini) — this is important research, quality matters
Captain reply: [recorded after decision]

5. Watch Rule

Every reply starts with current Taipei time:

⏰ 2026-03-05 17:33 (Taipei)

Not a formatting preference — agents without time awareness make decisions on stale knowledge. The watch is a safety mechanism.

---

Anti-patterns

Anti-pattern	Why it's bad	Instead
"Do your best"	No measurable criteria	Define acceptance criteria in WO
Loading all context upfront	Token waste, attention dilution	Use PD layers
Hardcoding version numbers	Becomes stale	Use "current version" + verification
Trusting training knowledge	10+ month lag	Search UB, then verify perishable knowledge
One giant CLAUDE.md	Slow to load, hard to maintain	Split into rules + skills
Agent asks Captain what to do	Wastes Captain time	Agent proposes, Captain decides

---

Related pages

Page	Relationship
Agent Intelligence Protocol	The 8 mandatory behaviors
Pre-Flight Check	3D risk assessment before tasks
Research-Before-Plan	Knowledge verification protocol
EGS Spec	The engineering rulebook
Cost Awareness	Token discipline for Opus agents