🏗️ CRAFT Framework

AI Knowledge Architecture Engine

Your AI is only as good as the knowledge you give it.

---

The Problem

The most powerful AI in the world, given poorly structured knowledge, will perform like a poorly informed assistant. Most AI customization fails not because of the model — but because of the knowledge architecture.

CRAFT fixes that.

What Is This?

A systematic framework for injecting custom knowledge into AI systems. It covers system prompts, RAG knowledge bases, few-shot examples, and context engineering — with a complete testing methodology to verify the AI actually uses the knowledge correctly.

The Iron Law: The AI's quality ceiling is set by your knowledge architecture, not the AI's capacity.

The CRAFT Workflow

Phase	Name	What You Do
C	Clarify	Extract the Knowledge DNA — role, rules, facts, failure modes
R	Restructure	Organize knowledge for AI consumption, not human reading
A	Architect	Assign knowledge to the right injection layer
F	Few-Shot	Write 3-5 examples that teach HOW to apply knowledge
T	Test	Verify with application scenarios, not "do you understand?"

The 4 Injection Methods

Method	Best For	Token Budget	Update Frequency
System Prompt	Identity, hard rules, Tier-1 knowledge	≤ ~2,000 tokens	Rarely
RAG	Large domain knowledge, frequently updated facts	Unlimited	As needed
Few-Shot Examples	Teaching HOW to apply knowledge	500-1,500 tokens	When behavior drifts
Context Engineering	User-specific data, session state	Per-session	Every session

The Knowledge Architecture Pyramid

Information at higher layers always wins in conflicts:

  ┌─────────────────────┐
  │  ROLE & IDENTITY    │  ← Highest priority. Non-negotiable.
  ├─────────────────────┤
  │  HARD RULES         │  ← Override everything below.
  ├─────────────────────┤
  │  CORE KNOWLEDGE     │  ← 5-10 items, always present.
  ├─────────────────────┤
  │  FEW-SHOT EXAMPLES  │  ← How to apply the knowledge.
  ├─────────────────────┤
  │  DYNAMIC KNOWLEDGE  │  ← RAG / Context. Retrieved per query.
  └─────────────────────┘

Quick Start

As a Human Framework

Read the core workflow, then study the worked example — a full CRAFT execution building a customer support AI.

As an AI / IDE Skill

Drop the skill/ directory into your coding agent's skill folder:

Agent	Installation
Antigravity	Copy skill/ to .agent/skills/customizing-ai-knowledge/
Claude Code	Reference skill/SKILL.md in ~/.claude/CLAUDE.md
Codex	Symlink skill/SKILL.md into ~/.codex/skills/craft/
Cursor	Add skill/SKILL.md to .cursor/rules/

Then trigger it with natural language:

"Create a system prompt for a customer support bot"
"Build a RAG knowledge base for our product docs"
"Why is my AI ignoring custom knowledge?"

The 8 AI Teaching Principles

#	Principle	One-Line Rule
1	Retrieval Architecture	Label everything. Put critical info first.
2	Spaced Reinforcement	Critical rules appear in rules AND examples AND style.
3	Cognitive Load	5-7 major sections max. Move the rest to RAG.
4	Dual Encoding	Every rule has a statement + a matching example.
5	Interleaving	Place rules adjacent to their examples, not separated.
6	Mastery Gating	Mark hard rules [ABSOLUTE]. Separate visually.
7	Contradiction Elimination	Audit for conflicts before deployment.
8	Feynman Test	Test with APPLICATION scenarios, never "do you understand?"

Repository Structure

craft-framework/
├── README.md                    # You are here
├── LICENSE                      # MIT License
├── CONTRIBUTING.md              # How to contribute
├── CHANGELOG.md                 # Version history
│
├── docs/                        # Human-readable documentation
│   ├── workflow.md              # The complete CRAFT workflow
│   ├── teaching-principles.md   # The 8 AI Teaching Principles
│   └── failure-diagnosis.md     # When AI ignores your knowledge
│
├── skill/                       # IDE / AI agent skill (drop-in)
│   ├── SKILL.md                 # Main skill instructions
│   └── resources/               # Supporting references
│       ├── FAILURE-CURRENT.md   # Failure current & audit cycle
│       ├── RAG-ARCHITECTURE.md  # RAG chunking & retrieval testing
│       └── SCALING.md           # Single AI → organization scaling
│
├── examples/                    # Worked examples
│   └── worked-example.md        # Full CRAFT: customer support bot
│
└── .github/                     # GitHub configuration
    └── ISSUE_TEMPLATE/
        ├── new-example.md       # Template for contributing examples
        └── improvement.md       # Template for framework improvements

Failure Diagnosis — Quick Reference

Symptom	Root Cause	Fix
AI gives generic answers	Knowledge buried in long prompt	Move Tier-2 to RAG; label Tier-1 explicitly
AI quotes verbatim, won't synthesize	No synthesis examples	Add few-shot examples showing synthesis
AI contradicts itself	Conflicting rules or chunks	Run contradiction probe audit
Right knowledge, wrong context	No scope labels	Add "When user asks about X, apply..."
AI breaks rules under pressure	Rules not marked absolute	Add [ABSOLUTE] labels + boundary example
RAG retrieves wrong chunks	Chunks too large or topics bleed	Re-chunk at semantic boundaries

Part of the Living Practice Ecosystem

This framework was built using The Way of Water V2 and integrates with Verify AI Output for testing AI knowledge customization results.

Contributing

See CONTRIBUTING.md. The most valuable contributions are:

• New worked examples — full CRAFT executions in different domains
• Failure pattern discoveries — AI knowledge failures you've encountered
• RAG architecture patterns — domain-specific chunking strategies

License

MIT — use freely, architect wisely.

---

Living Practice — Iteration 1.0

The AI's ceiling is your knowledge architecture.