AGENTS.md

AGENTS.md

Project Overview

Jekyll static site (personal blog) deployed to GitHub Pages at gdunhao.com. Uses the Minima theme with heavy custom overrides — not a vanilla Minima site.

Architecture

</aside> `.

  • Sidebar-first design: The Minima site-header is hidden with CSS (:has(.home-with-sidebar)) and replaced by a fixed sidebar (_includes/sidebar.html). Every content layout wraps content in div.home-with-sidebar. Do not add layouts without this wrapper or the nav will break.
  • Styling: assets/css/style.scss imports Minima then overrides ~1000 lines of custom SCSS. All custom styles live in this single file — there are no partials. The file requires empty front matter (---\n---) for Jekyll to process it.
  • Custom head.html: Loads Font Awesome 6.4 from CDN and links style.css (not main.css). Icons use FA classes like fab fa-github, far fa-calendar.
  • Category system: Posts are grouped into series via category index pages (e.g., java/java26.md, ai/augmenting-llms.md, ai/agents.md) that use layout: category with permalink and category front matter. The category.html layout filters posts by page.category. To add a new series: create a top-level dir with an index .md, a matching _posts/<topic>/<series>/ subdirectory, and add a nav entry in _includes/sidebar.html.
  • Sidebar nav: Navigation links in _includes/sidebar.html are hardcoded, not generated from data. Category groups use a CSS-only collapsible pattern (<input type="checkbox"> + <label> + :checked sibling selector). When adding a new category series, manually add a sidebar-nav-group block to sidebar.html.

Key Configuration (_config.yml)

Site identity and sidebar content are driven by config values: author.name, bio, avatar, tagline, github_username, twitter_username, linkedin_username. Update these in _config.yml, not in templates. Changes to _config.yml require a server restart.

Development

bundle install                          # install dependencies
bundle exec jekyll serve --livereload   # dev server at localhost:4000
bundle exec jekyll serve --drafts       # include _drafts/ posts
bundle exec jekyll build                # build to _site/

Creating Posts

File: _posts/<topic>/<series>/YYYY-MM-DD-title.markdown (e.g., _posts/java/java26/2026-03-18-java26-http3.markdown). Front matter:

---
layout: post
title: "Title"
date: YYYY-MM-DD HH:MM:SS +0100
categories: topic series
---

Categories use a two-level scheme: the first category is the broad topic (e.g., java, ai) and the second is the series slug (e.g., java26, augmenting-llms). Both must match the category index page’s category front matter for the post to appear in the series listing. Nested topics (e.g., spring spring-ai rag) use additional intermediate categories — the category.html layout filters on the innermost slug via contains.

Review Workflow (Pre-publish Posts)

Place posts-in-progress in _posts/review/. They are built by Jekyll (accessible via direct URL) but hidden from all public listings (home page, category pages, RSS feed). The mechanism is a review: true front matter flag — both home.html and category.html filter with where_exp: "post", "post.review != true".

Review post front matter — set categories to the final destination so the URL won’t change after publishing:

---
layout: post
title: "My Draft Post"
date: 2026-04-03 10:00:00 +0100
categories: java java26
review: true
---

The post will be live at its direct URL (e.g., /java/java26/2026/04/03/my-draft-post/) but invisible in all listings.

To publish: remove review: true from the front matter, then move the file to _posts/java/java26/ (or the appropriate topic/series folder). The post will immediately appear in the home page and category listing.

⚠️ The RSS feed (/feed.xml) is generated by the jekyll-feed plugin and cannot be easily filtered — review posts will technically appear there. This is acceptable for a personal blog.

Conventions

  • Layouts always include the sidebar — home.html, post.html, page.html, and category.html all use the home-with-sidebar + sidebar.html pattern. New layouts must follow this.
  • No JavaScript — the site is pure HTML/CSS; avoid adding JS unless explicitly requested. Exception: post.html has a small inline script that opens post-content links in new tabs (target="_blank").
  • Responsive breakpoint: 1024px — sidebar collapses from fixed left column to stacked top section. Maintain this breakpoint in new styles.
  • _site/ is generated output — never edit files there; they are overwritten on build.
  • Diagrams: Posts embed SVG diagrams stored in assets/images/diagrams/<series>/ (e.g., assets/images/diagrams/ai-agents/). Use this HTML pattern inside posts: 
    <figure>
  <img src="/assets/images/diagrams/%3Cseries%3E/%3Cname%3E.svg" alt="Descriptive alt text." loading="lazy">
</figure>

    SVG files must contain valid content — the pre-commit hook blocks empty image files.

  • Diagram color system (canonical): All new and updated SVG diagrams must follow the same dark theme and color family used in assets/images/diagrams/augmenting-llms/augmenting-vs-training-spectrum.svg.
    • Base surfaces: #0d1117 (background), #161b22 (surface), #21262d/#30363d (dividers and borders).
    • Text: #f0f6fc or #e6edf3 (primary), #8b949e (muted), #58a6ff (link/accent text).
    • Spectrum accents: #2ea043, #3daa3d, #3fb950, #56d364, #4cae52, #9e6a03, #d29922, #e3b341, #f0883e, #e55c5c, #f85149, #cf222e.
    • Gradients: Reuse the green→amber→red progression (#2ea043 → #9e6a03 → #cf222e) for top bars and spectrum rails when a gradient is needed.
    • Rule of use: Prefer these colors over ad-hoc hex values. If a diagram needs a one-off color for clarity, keep it minimal and close to this palette.
    • Migration target: Existing diagrams should be progressively normalized to this palette when they are edited or refreshed.
  • Git hooks: .githooks/pre-commit blocks commits containing empty staged image files (.svg, .png, .jpg, etc.). Activate with git config --local core.hooksPath .githooks.
  • Deployment: push to main branch triggers GitHub Pages auto-deploy. CNAME file maps the custom domain.

Content: Spring AI RAG Series (spring/spring-ai/rag)

A hands-on series building RAG systems with Spring AI. Each post maps to a demo in the rag-spring-ai project. Posts live in _posts/spring/spring-ai/rag/. Category index: spring/spring-ai/rag.md. Diagrams: assets/images/diagrams/spring-ai-rag/.

Three-level categories: Posts use categories: spring spring-ai rag. The sidebar uses a nested collapsible group (Spring > Spring AI > RAG). The category.html filter matches on the innermost slug (rag).

Published Posts

Date File Title
2026-04-12 2026-04-12-basic-rag-spring-ai.markdown Basic RAG with Spring AI: Build a Grounded Q&A System from Scratch
2026-04-16 2026-04-16-document-ingestion-spring-ai.markdown Document Ingestion with Spring AI: Loading Text, JSON, and Custom Chunks into Your RAG Pipeline
2026-04-20 2026-04-20-vector-store-operations-spring-ai.markdown Vector Store Operations with Spring AI: Similarity Search, Thresholds, and Embedding Inspection
2026-04-23 2026-04-23-chat-with-memory-spring-ai.markdown Chat with Memory in Spring AI: Conversational RAG That Actually Remembers
2026-04-26 2026-04-26-advisors-spring-ai.markdown Advisors in Spring AI: Composing RAG, Memory, and Safety as a Pipeline
2026-04-29 2026-04-29-structured-output-spring-ai.markdown Structured Output in Spring AI: Turning LLM Prose into Typed Java Records

Planned Posts (map to rag-spring-ai demos)

Demo What it adds
Function Calling Letting the LLM invoke Java methods as tools
Multi-Document RAG Multiple document collections with smart routing
Metadata Filtering Scoping vector search with metadata filters

Diagrams

All diagrams in assets/images/diagrams/spring-ai-rag/. Follow the canonical dark-theme color system. Current SVGs: rag-overview.svg, rag-ingestion-pipeline.svg, rag-query-flow.svg, rag-spring-ai-architecture.svg, rag-basic-playground.svg, ingestion-reader-abstraction.svg, ingestion-strategies.svg, ingestion-chunk-size-comparison.svg, vector-store-operations.svg, vector-store-similarity-threshold.svg, chat-memory-flow.svg, advisors-pipeline.svg, structured-output-flow.svg, structured-output-vs-freetext.svg.

Content: AI Agents Series (ai/agents)

Posts live in _posts/ai/agents/. Category index: ai/agents.md. All diagrams are in assets/images/diagrams/ai-agents/.

Published Posts

Date File Title
2026-04-02 2026-04-02-ai-agents.markdown AI Agents: Autonomous Systems That Reason, Plan, and Act
2026-04-03 2026-04-03-ai-agents-best-practices.markdown AI Agents Best Practices: Building Reliable, Safe, and Effective Agent Systems
2026-04-04 2026-04-04-single-react-agent-deep-dive.markdown Deep Dive: Single ReAct Agent
2026-04-05 2026-04-05-multi-agent-systems-deep-dive.markdown Deep Dive: Multi-Agent Systems — Architectures, Coordination Patterns, Best Practices, and Pitfalls
2026-04-06 2026-04-06-hierarchical-agents-deep-dive.markdown Deep Dive: Hierarchical Agent Systems — Supervisors, Workers, Delegation, and Quality Control

Architecture Patterns Implemented

1. Single ReAct Agent (react-*, single-agent-react.svg, agent-loop.svg, agent-components.svg)

The foundational agent loop: Thought → Action → Observation, repeated until the goal is met or a budget is exceeded. One LLM acts as the reasoning engine and selects from a set of bound tools.

  • Internal architecture: system prompt + context window accumulates (thought, action, observation) tuples; LLM generates the next thought at each step.
  • Core components: Reasoning engine, Planning module, Memory (short-term context + long-term store), Tool belt.
  • Decision flow: Use when the task needs tools and multi-step reasoning, and one agent with the right tools can cover the full domain. Escalate to multi-agent only when this demonstrably fails.
  • Best practices (8 principles): Design tools for the LLM (clear names, narrow scope, JSON schemas); set budgets and guardrails; use structured outputs; manage context window; invest in observability; sandbox code execution; evaluate on trajectories; implement graceful failure.
  • Common failure modes: Infinite loop (fix: max iterations + wall-clock timeout); wrong tool selection (fix: clear tool names, strict schemas, non-overlapping tools); context overflow (fix: summarise or prune history); prompt injection via tool outputs.
  • Diagrams: react-architecture.svg, react-detailed-loop.svg, react-decision-flow.svg, react-best-practices.svg, react-failure-modes.svg, react-trace-example.svg, single-agent-react.svg, agent-loop.svg, agent-components.svg.

2. Multi-Agent Systems (multi-agent-*)

Two or more specialized LLM agents — each with its own role, system prompt, tools, and constraints — coordinated by an orchestration layer. Agents communicate through shared state, not direct LLM-to-LLM conversation.

  • Topologies:
    • Sequential Pipeline — each agent passes output to the next (Researcher → Writer → Reviewer).
    • Parallel Fan-Out / Fan-In — agents work concurrently on independent subtasks; orchestrator merges results.
    • Hierarchical Supervisor — a supervisor agent delegates subtasks to workers, reviews outputs, and iterates (see pattern 3 below).
  • Handoff mechanism: structured typed payloads (intent + entities + history + metadata) passed between agents, never raw chat logs.
  • Shared state architecture: all agents read/write to a shared state store (not each other); orchestrator reads state to decide routing.
  • Decision flow: use when a single ReAct agent fails due to context limits, role confusion, or breadth requiring different tools per phase. Use explicit (deterministic code) routing, not LLM-driven routing.
  • Best practices (8 principles): Single-responsibility agents; explicit/deterministic orchestration; structured handoff payloads; shared state store; idempotent tool calls; per-agent budgets; tracing across agent boundaries; graceful degradation on agent failure.
  • Common failure modes: Agent ping-pong / handoff loops (fix: max handoff depth + timeout); context loss on handoff (fix: structured payloads); orchestrator hallucination of non-existent agents (fix: deterministic routing in code).
  • Diagrams: multi-agent-collaboration.svg, multi-agent-topologies.svg, multi-agent-handoff.svg, multi-agent-shared-state.svg, multi-agent-best-practices.svg, multi-agent-decision-flow.svg, multi-agent-execution-trace.svg, multi-agent-failure-modes.svg.

3. Hierarchical Supervisor-Worker Pattern (hierarchical-*)

A specific multi-agent topology where a supervisor agent decomposes a high-level goal, delegates subtasks to worker agents, reviews their outputs, and iterates until the result meets a quality bar. Workers never talk to each other directly.

  • Delegation cycle: Supervisor decomposes → delegates subtask (with typed spec + acceptance criteria) → worker executes its own ReAct loop → supervisor reviews → if quality gate fails: request revision (capped at 2–3 rounds) → if passes: accept and continue or finalize.
  • Internal architecture: supervisor holds delegate_to_worker, request_revision, approve_output tools and reads shared state to decide routing; each worker has scoped tools and writes specific state fields.
  • Key differentiators from flat multi-agent: centralized control (single point of accountability), built-in quality review loop, task decomposition as a first-class concern.
  • Decision flow: use when tasks need multi-step decomposition and different tools/expertise per subtask and output quality requires iterative review. Fall back to sequential pipeline when quality review is not needed.
  • Best practices (8 principles): Thin supervisor (decompose and delegate only, never do worker tasks); structured task specs with acceptance criteria; bounded revision rounds (max 2–3 then escalate); worker isolation (workers see only their own tools and task); idempotent workers; supervisor budget separate from worker budgets; trace supervisor decisions separately; clear escalation path on repeated failure.
  • Common failure modes: Supervisor micro-management (fix: strict role in system prompt — “You ONLY decompose and delegate”); infinite revision loop (fix: cap at 2–3 revision cycles, then escalate); bad task decomposition with overlapping or missing subtasks (fix: validate plan schema before execution).
  • Diagrams: hierarchical-agents.svg, hierarchical-architecture.svg, hierarchical-delegation-cycle.svg, hierarchical-decision-flow.svg, hierarchical-best-practices.svg, hierarchical-execution-trace.svg, hierarchical-failure-modes.svg.

Cross-Cutting Patterns (Best Practices Post)

These patterns apply across all agent architectures and are covered in 2026-04-03-ai-agents-best-practices.markdown.

Pattern SVG Summary
Complexity Ladder agent-complexity-ladder.svg Escalate left-to-right only when simpler architecture fails: Single LLM call → Single-agent ReAct → Multi-agent.
Budget Guardrails agent-budget-guardrails.svg Bound every agent loop with a step limit (e.g. 25), token budget, wall-clock timeout, and per-tool retry cap. Return a graceful fallback when any limit is hit.
Human-in-the-Loop Approval Gate human-approval-gate.svg Pause before irreversible or high-stakes actions (deletes, payments, deploys) and require explicit human approval, rejection, or modification.
Observability & Tracing agent-observability-trace.svg Capture the full agent trajectory: every thought, tool call, tool output, token count, latency, and final answer — with cost attribution per step.
Code Execution Sandboxing agent-sandbox-boundary.svg Never execute agent-generated code on the host. Route all untrusted code across a hard isolation boundary into Docker, E2B, or Firecracker with non-root permissions, restricted filesystem, restricted network, and a kill budget.