What You'll Build
A browser-based document chunking agent that reads a pasted document, splits it using a strategy you choose, wraps each chunk in engineered context, and then runs an agent loop to answer questions over the full document — showing you exactly which chunk it used and why.
- Multiple chunking strategies: fixed-size, sentence-boundary, and semantic-section splitting
- Context engineering: each chunk gets a header with document title, chunk index, neighbour summary, and topic label
- An AI agent loop that retrieves the best chunk, reasons over it, and decides if it needs more
- Chunk viewer panel that shows every chunk, its context header, and token estimate
- Q&A interface with source attribution — see exactly which chunk answered your question
- Agent reasoning trace visible in the UI so you can see every step it took
What You'll Need
Claude (claude.ai)
Claude is your coding partner and the AI engine inside your finished agent. You'll prompt Claude to write the code, and then your built tool will call Claude's reasoning to power the agent loop. A free account works for building; the agent Q&A works best with Claude Sonnet or above.
A Text Editor
VS Code, Cursor, or any editor you're comfortable with. You'll save a single HTML file with embedded JavaScript — no build tools, no npm install. Just open the file in your browser and you're running.
This project is advanced because it ties together three big ideas at once: how you split a document changes what an AI can see; how you wrap each chunk in context changes what it can reason about; and building an agent loop changes how it decides what to look at next. Let's build all three layers together.
Step 1: Build the Document Input and Chunking Engine
Every great RAG-style system starts with one decision that shapes everything downstream: how do you split the document? You'll build a chunking engine with three real strategies — fixed-size (split every N characters), sentence-boundary (split on full stops and newlines), and semantic-section (split on headings and blank lines). The strategy you pick determines what context your agent can actually see, so we'll make it switchable at runtime.
Paste the prompt below into Claude and tell it what file type you're mostly working with (plain text, markdown, or article-style prose). Claude will generate the full HTML skeleton, the textarea for document input, and the three chunking functions.
I'm building a context-aware document chunking agent as a single self-contained HTML file with embedded JavaScript. No frameworks, no npm, no external dependencies except a script tag for Tailwind CDN. Step 1: Build the document input layer and chunking engine. Create an HTML file with a dark-themed UI that includes: 1. A large textarea where I can paste any document (plain text or markdown) 2. A document title input field 3. A chunking strategy selector with three options: - Fixed-size: splits every 500 characters, tries to break on a space - Sentence-boundary: splits on '. ' or newlines, grouping until ~400 chars - Semantic-section: splits on markdown headings (## or #) or double newlines 4. A "Chunk Document" button that runs the selected strategy 5. A chunk viewer panel below that renders each chunk as a card showing: - Chunk index (e.g. "Chunk 3 of 12") - Estimated token count (approximate: characters / 4) - The raw chunk text - A coloured border that changes per strategy (violet for fixed, amber for sentence, cyan for semantic) Implement all three chunking functions in JavaScript. Make the UI dark-themed using Tailwind. Show a summary bar after chunking: total chunks, average chunk size in tokens, and which strategy was used. Don't add the AI agent or Q&A yet — just the chunking engine working cleanly.
What to look for
Claude should give you a complete HTML file you can save and open in a browser immediately. Paste a few paragraphs of text and try all three strategies — you should see noticeably different chunk counts and sizes. The fixed strategy will be the most mechanical, while semantic-section should create the largest but most coherent chunks. If any strategy produces just one giant chunk, ask Claude to debug that function specifically.
Step 2: Add Context Engineering to Every Chunk
Raw chunks are just text blobs. The insight from context engineering is that what surrounds the chunk — its metadata, its position in the document, a summary of what came before — changes what an AI can reason about, even if the chunk text itself is identical. This is the upgrade from prompt engineering to context engineering: you're not just writing better questions, you're shaping the information structure around every piece of data the AI touches.
In this step you'll add a context-engineering layer that wraps each raw chunk in a structured header before any AI ever sees it. This header becomes the "engineered context" that makes your agent dramatically smarter.
Now add a context engineering layer to the chunking engine from Step 1. After chunking, each chunk should be wrapped in a structured context header before being stored in memory. This header is NOT shown to the user in the chunk viewer, but IS prepended to the chunk text whenever it gets sent to the AI. The context header should follow this exact template for each chunk: ---CHUNK CONTEXT--- Document: [document title from input field] Strategy: [chunking strategy used] Chunk: [index] of [total] Prev summary: [first 80 chars of previous chunk, or "Start of document" if first] Next hint: [first 40 chars of next chunk, or "End of document" if last] Topic guess: [extract the first noun phrase or heading from this chunk, max 6 words] ---END CONTEXT--- [raw chunk text here] Add a toggle in the UI called "Show context headers" that lets the user flip between seeing the raw chunk and seeing the full context-wrapped version in the chunk viewer cards. Also add a global stats line that shows the total token estimate WITH context headers vs WITHOUT, so I can see how much overhead the context engineering adds. Don't touch the chunking logic — only add the context wrapping layer on top of existing chunks.
What to look for
Toggle "Show context headers" on and look at a middle chunk — you should see the prev summary referencing the chunk before it and the next hint pointing forward. The topic guess won't be perfect (it's JavaScript, not an LLM), but it should pull the dominant noun from the chunk. Check the token overhead stat: for short chunks, context headers can add 30–50% overhead, which is a concrete illustration of why chunking strategy and context engineering are inseparable decisions.
Step 3: Build the AI Agent Loop
An agent is just a loop with a decision at the end: look at what I have, decide if it's enough, and either answer or fetch more. In this step you'll build that loop using the Claude API. The agent gets a question, searches the chunk store for the best keyword match, reads that context-wrapped chunk, and decides: "Can I answer this from what I have, or do I need to look at another chunk?" It keeps going until it can answer or it's looked at five chunks.
You'll need a Claude API key for this step. The agent calls Claude with a structured system prompt that instructs it to either return a JSON object with an answer or a JSON object requesting the next chunk index to look at — that's the agent loop protocol.
Now add the AI agent loop to the tool. Here's exactly how it should work:
1. Add a Q&A section below the chunk viewer with a question input and "Ask Agent" button.
2. Add an API key input field at the top (stored only in memory, never sent anywhere except the Claude API).
3. When the user asks a question, run this agent loop in JavaScript:
AGENT LOOP PROTOCOL:
a. Start with chunk index 0 (or whichever chunk has the most keyword overlap with the question — do a simple word-match score across all chunk texts to pick the starting chunk).
b. Send Claude this system prompt:
"You are a document Q&A agent. You will receive one context-wrapped chunk at a time. After reading it, you must respond with valid JSON only — no prose, no markdown. Either: {\"action\": \"answer\", \"answer\": \"your answer here\", \"confidence\": \"high|medium|low\"} if you can answer the question from this chunk, OR {\"action\": \"fetch\", \"next_chunk\": , \"reason\": \"why you need that chunk\"} if you need to look at another chunk. You may look at up to 5 chunks total before you must answer."
c. Send the user's question and the current context-wrapped chunk as the user message.
d. Parse Claude's JSON response. If action is "fetch", load that chunk and loop. If action is "answer", stop.
e. Cap the loop at 5 iterations.
4. Display an "Agent reasoning trace" panel that shows each step: which chunk was fetched, Claude's decision, and the reason. Make each step a card with the chunk index, a summary of the decision, and a timestamp.
5. Show the final answer prominently with a "Source: Chunk X" badge and the confidence level colour-coded (green = high, amber = medium, rose = low).
Use the Claude API endpoint: https://api.anthropic.com/v1/messages with model claude-3-5-haiku-20241022 for speed. Include proper error handling for API failures.
What to look for
Ask something that's clearly in the middle of your document — the agent should start near the right chunk thanks to keyword scoring, then either answer immediately or fetch one more. Watch the reasoning trace: you want to see Claude's "reason" field explaining why it needed a different chunk. If the agent always says confidence is "low", your chunks may be too small — try switching to semantic-section chunking and ask again.
Step 4: Add Strategy Comparison Mode
The whole point of understanding chunking strategies is seeing how they affect real results. In this step you'll add a "Compare strategies" mode that runs the same question through all three chunking strategies and shows you the answers side by side — so you can see, concretely, how splitting decisions change what an AI can reason about. This is context engineering made visible.
This step also improves the chunk viewer with highlighting — when the agent uses a chunk to answer, that chunk card gets highlighted in the viewer so you can see exactly which piece of text the answer came from.
Add two improvements to the agent tool:
1. STRATEGY COMPARISON MODE
- Add a "Compare All Strategies" button in the Q&A section.
- When clicked, it runs the same question through all three chunking strategies sequentially (fixed, sentence, semantic), using the same document and question.
- Display a comparison panel with three columns (or stacked cards on mobile), one per strategy, each showing:
* Strategy name and chunk count
* Final answer from the agent
* Confidence level
* Number of agent loop iterations (how many chunks it had to read)
* Total estimated tokens consumed (chunks read × average chunk token size)
- Highlight the "winner" card (lowest iterations + highest confidence) with a brand green border.
2. CHUNK HIGHLIGHTING
- When the agent finishes and has used specific chunk indices to answer, scroll the chunk viewer to the first source chunk and add a glowing ring highlight (use a ring-2 ring-brand-400 style) to each chunk card that was read during the agent loop.
- Chunks that were read but not the final source should get a dimmer ring (ring-zinc-500).
- Add a small label on highlighted chunks: "Used by agent" or "Scanned".
- Reset highlights when a new question is asked.
Keep all existing functionality intact — don't break the single-strategy mode.
What to look for
Run the comparison on a meaty question that requires context from a specific section of your document. You'll likely see fixed-size chunking need more iterations (because relevant info gets split across chunks), while semantic-section chunking answers in one or two iterations but uses more tokens per chunk. That trade-off — iterations vs token cost — is exactly the insight from the chunking strategies tutorial made real and measurable.
Step 5: Polish, Export, and Add a CLAUDE.md-Style Config Panel
A finished tool needs two things: a way to save your work and a way to configure behaviour without touching the code. In this final step you'll add a configuration panel inspired by CLAUDE.md — a set of persistent instructions that tell the agent how to behave for a specific document type. You'll also add JSON export so you can save your chunks and the full agent session for later use.
The config panel is where context engineering meets agent design: you're writing standing instructions that get prepended to every agent call, shaping how it reasons about the domain of your document.
Add two final features to finish the tool:
1. AGENT CONFIG PANEL (inspired by CLAUDE.md project-level instructions)
- Add a collapsible "Agent Config" panel at the top of the page, collapsed by default.
- Inside it, a textarea labelled "Standing instructions for this document" with placeholder text: "e.g. This is a legal contract. Always cite clause numbers. Prefer precise language over summaries. Flag any ambiguous terms."
- These standing instructions get prepended to the agent's system prompt on every API call, before the chunk protocol instructions.
- Add three preset buttons that fill in example configs: "Legal Document", "Technical Spec", "Meeting Notes" — each with a useful pre-written instruction set.
- Show a small badge in the Q&A section when standing instructions are active: "Config active: [first 30 chars of instructions]..."
2. JSON EXPORT
- Add an "Export Session" button that downloads a JSON file containing:
* Document title and original text
* Chunking strategy used
* All chunks with their context headers
* All Q&A pairs from the session (question, answer, confidence, chunks read, strategy used)
* Timestamp and total tokens estimated
- Format the filename as: [document-title]-[strategy]-session.json
3. FINAL POLISH
- Add a top nav bar with the tool name "ChunkAgent" and a small tagline: "Context-aware document Q&A"
- Make sure the layout is clean on a 1280px screen with a two-column layout: chunk viewer on the left (60%), agent panel on the right (40%)
- Add empty states to every panel (friendly messages when no document is loaded yet)
- Do a full pass and make sure there are no console errors when the page loads fresh
This is the final version — make it feel complete and polished.
What to look for
Try the "Legal Document" preset config, then ask a vague question — the agent's standing instructions should push it toward precise answers. Export a session JSON and open it: you should see every chunk with its full context header, which is a great way to audit whether your context engineering is actually capturing what you intended. If the two-column layout collapses on your screen, ask Claude to adjust the breakpoints.
Common Issues
The agent always reads all 5 chunks before answering
Your chunks are probably too small and the relevant information is spread across many of them. Switch to semantic-section chunking, which keeps related content together. Also check your context headers — if the "prev summary" is cut off mid-sentence it might be confusing the agent's navigation decisions.
Claude returns prose instead of JSON in the agent loop
The agent system prompt needs to be more forceful. Ask Claude to update the system prompt to add: "You MUST respond with valid JSON only. If you respond with anything other than a JSON object, the system will crash. No markdown code fences, no explanations, just the raw JSON object." That usually fixes it.
CORS errors when calling the Claude API from the browser
The Anthropic API doesn't support direct browser calls without a proxy because of CORS restrictions. Ask Claude to add a note about this and refactor the API call to use a simple localhost proxy, or switch to running the HTML file via a local server with VS Code's Live Server extension rather than a file:// URL.
The comparison mode fires all three strategies at once and the UI freezes
The three strategies should run sequentially, not in parallel — awaiting each before starting the next. Ask Claude to refactor the comparison function to use async/await with sequential execution rather than Promise.all, and add a "Running strategy X of 3..." progress indicator between each run.
Context headers are showing in the chunk viewer even when the toggle is off
There are likely two places where chunk text is rendered — the viewer cards and the comparison panel. Ask Claude to create a single helper function getChunkText(chunk, showContext) that's called everywhere, so the toggle flag only needs to be checked in one place.
What You Learned
Chunking Is a Design Decision
You implemented three real strategies and measured their trade-offs: token cost, iteration count, and answer quality. Splitting decisions shape everything that comes after — this is the core lesson from the chunking strategies tutorial, now made tangible.
Context Engineering Over Prompting
You wrapped every chunk in structured metadata before any AI saw it. The context header — position, neighbours, topic — changed what the agent could reason about without changing the chunk text at all. That's the shift from prompt engineering to context engineering.
Agent Loops in Practice
You built a real observe-decide-act loop in JavaScript: the agent observed a chunk, decided whether it had enough to answer, and either responded or fetched the next chunk. That's the same pattern that powers production AI agents, just made visible.
Standing Instructions as Agent Config
Your config panel showed how project-level instructions (like a CLAUDE.md file) change agent behaviour for a specific domain without modifying code. The same agent handles legal docs and meeting notes differently based purely on the standing instructions you prepend.
Tips for Going Further
- → Add overlap between chunks. Real RAG systems use overlapping windows (e.g. 50-char overlap between adjacent chunks) to avoid cutting a sentence mid-thought. Add an overlap slider and see how it affects the agent's answer quality on boundary-crossing questions.
- → Replace keyword search with real embeddings. Swap the word-match chunk selector for a call to OpenAI's text-embedding-ada-002 or a local model, and use cosine similarity to find the most semantically relevant starting chunk — not just the one with the most matching words.
- → Load documents from files. Add a file input that accepts .txt and .md files so you don't have to paste content. Try it with a long README or a technical spec and watch the semantic-section chunker split it on headings automatically.
- → Build a multi-document agent. Extend the tool to hold multiple documents in memory, each pre-chunked with their own strategy. The agent then decides which document to fetch from first — a proper multi-source reasoning system.
- → Persist sessions with localStorage. Save chunked documents and Q&A history to localStorage so they survive a page refresh. Add a session picker to load previous documents without re-chunking.