Skill Deep Dive

project-context

Persistent project knowledge files that give AI agents instant context across sessions

7 Knowledge Files

2 Hook Events

200 Max Lines/File

ai-servicers.com

The Problem

AI agents lose project context between sessions.

Every new session, Claude re-discovers architecture, re-learns gotchas, and re-makes decisions that were already settled. Subagents spawned mid-task have zero project knowledge.

CLAUDE.md is for directives (what to do), not knowledge (what IS). We need a separate system for persistent project facts.

7 Knowledge Files

architecture.md

Components, tech stack, data flow, integrations, design patterns

"What IS this system?"

decisions.md

ADR-style entries: context, decision, rejected alternatives

"Why was it built this way?"

security.md

Auth model, secrets locations, required/forbidden patterns

"What must never be violated?"

operations.md

Prerequisites, env vars, build/deploy commands, health checks

"How do you run/deploy it?"

testing.md

Strategy, commands, coverage targets, known issues

"How is correctness verified?"

gotchas.md

Symptom → Cause → Fix for non-obvious behaviors

"What will waste your time?"

specs.md

Core value, business rules, active requirements, API contracts

"What are the business rules?"

File Structure

projects/my-service/
  docs/
    context/
      architecture.md
      decisions.md
      security.md
      operations.md
      testing.md
      gotchas.md
      specs.md
  CLAUDE.md # directives (what to do)

Design Decisions

Topic-based, not role-based — agents don't have fixed roles
docs/context/ — Claude checks docs/ first instinctively
Committed to git — travels with repo, history tracked
200 lines max per file — forces conciseness
Project opt-in — hooks only fire if docs/context/ exists

Status Markers

Every entry is prefixed with its implementation status. Agents must clearly distinguish fact from plan.

## Components
- [IMPLEMENTED] PostgreSQL for primary data store
- [IMPLEMENTED] Traefik reverse proxy with OAuth2
- [PLANNED] Redis cache layer for session management
- [DEPRECATED] MongoDB connector (removed in v2)

Rules

[IMPLEMENTED] — actual current state, verified working
[PLANNED] — future intent, NOT yet built
[DEPRECATED] — was implemented, now removed
No timestamps — git history tracks when

Automatic Trigger: Hooks

Agent Works

Agent writes code, edits files, makes decisions. No interruption during work.

Stop Event

Agent finishes responding. Stop hook fires. Checks git diff for changes.

Smart Check

3-tier logic: silent if docs updated, soft for decisions, strong for code changes.

Agent Updates

If reminded, agent updates relevant context files before finishing.

Two Hook Events

Stop — main agent finishes responding (fires once per turn)
SubagentStop — subagent finishes (runs in subagent context, doesn't disrupt main agent)

3-Tier Hook Logic

Condition	Hook Response	Agent Impact
`docs/context/` already updated	Silent	None — agent finishes immediately
`stop_hook_active: true`	Silent	Prevents infinite loop
No `docs/context/` directory	Silent	Project not opted in
No changes at all	Soft one-liner	"If significant decisions were made, update decisions.md"
Small code change (<15 lines diff)	Soft reminder	"If changes affect architecture/security/ops, update docs"
Significant code change, no docs update	Strong reminder	"You changed code. Update relevant docs/context/ files."

Detection uses git diff — deterministic, no LLM cost, <100ms

Writing Rules

Must Do

Bullet points and tables, never prose
Each entry is self-contained
Use [IMPLEMENTED] / [PLANNED] markers
Stay under 200 lines per file
Prune stale entries when full
Bundle with next code commit

Must Not Do

No prose paragraphs or narrative
No timestamps on entries
No duplicating CLAUDE.md content
No empty template sections
No separate context-only commits
No filler, pleasantries, or fluff

Routing Rule

When unsure which file to update, ask: "Which question does this answer?" Each file answers exactly one question. If torn between two files, pick the more specific one.

How to Use

Bootstrap

/project-context init

Creates docs/context/ with all 7 files from templates. Populates with known project info.

Manual Update

/project-context

Reads all context files, compares against current state, updates stale info, prunes outdated entries.

Automatic

Stop / SubagentStop hooks

Smart git diff reminds agents to update after significant changes. Zero config per project.

User-level infrastructure, project-level opt-in. Hooks are global but only fire when docs/context/ exists. Any project opts in by running /project-context init.

project-context

7 terse markdown files in docs/context/ give every agent instant project understanding without re-discovery.

Stop + SubagentStop hooks ensure updates happen automatically. Smart git diff keeps noise near zero — silent when docs are already current.

CLAUDE.md = directives. docs/context/ = knowledge. Clean separation. Both committed to git. Both available to every agent.

7 Knowledge Files

1 Stop per Turn

<100ms Hook Overhead

ai-servicers.com