Field ledger · Featured project

VibeKB

Understand your AI-built software.

Modern AI coding tools help us build software faster than ever. Understanding it hasn’t kept up. VibeKB transforms repositories into living understanding sites that help developers regain confidence, understand architecture, explore functionality, and safely continue development.

Focus repository understanding Built for AI-assisted workflows Public ideas 00

01 · Premise

Understanding before modification

AI coding tools let people build large applications quickly. After a few days or weeks, many struggle to answer basic questions about their own software.

VibeKB is a repository understanding platform designed for the age of AI-assisted software development. Instead of forcing developers to rediscover their own architecture, it helps them regain understanding and confidence—so they can see how the application works, where to make changes, and what could break if they do.

What it is

Repository understanding
Human-first explanation
Living project knowledge

What it is not

A code generator
A marketing pitch
A throwaway summary

It helps answer

How does this work
Where should I change
What depends on this

Built for

Solo developers
AI-assisted workflows
Returning to a codebase

02 · On the bench

Three capabilities in focus

Each capability exists to make software comprehension concrete: what the system does, how features relate, and where architecture lives in the files.

CAP-01

Human-first understanding

Core

Hypothesis

Developers regain confidence faster when a repository is explained in clear, structured, human-friendly language—not buried in raw file trees.

Problem being addressed

After building with AI, people often cannot answer how their application actually works. The code exists. The understanding does not. Returning after time away makes the gap worse.

Working product loop

Connect a repository→ Analyze with AI assistance→ Read a living understanding site

Evidence watched: Whether developers can explain their own system after time away, and whether they feel ready to modify it without rediscovering everything from scratch.
Technology: PHPAI analysisJavaScript
Decision gate: Does the understanding site restore functional comprehension faster than reading the repository alone?
Next experiment: Keep explanations current as the repository changes.

CAP-02

Feature-oriented exploration

Core

Hypothesis

Developers find the right place to work when they can explore software by feature and functionality, not only by folder and filename.

Problem being addressed

AI-generated repositories grow quickly. Files implement functionality, but the map from “what I want to change” to “which files matter” is often missing. Relationships between features stay opaque.

Working product loop

Browse by feature→ See related functionality→ Open the implementing files

Evidence watched: Whether people can locate the files behind a feature without hunting through the tree, and whether feature relationships reduce accidental breakage.
Technology: PHPAI analysisStructured views
Decision gate: Can a developer answer “what files implement this?” and “what depends on this?” from the understanding site?
Next experiment: Surface clear relationships between features as the primary navigation path.

CAP-03

Functional architecture mapping

Core

Hypothesis

Architecture clarity comes from mapping how the system behaves—not from generating more text about the code.

Problem being addressed

People can ship software they no longer understand. Without a functional map, every change feels risky. The question is not “what did the AI write?” but “how does this application hold together?”

Working product loop

Map functional structure→ Clarify module roles→ Assess change impact

Evidence watched: Whether architecture views help people predict what could break, and whether they continue development with less hesitation after time away.
Technology: PHPAI analysisArchitecture views
Decision gate: Does functional architecture mapping make safe continuation of AI-assisted projects feel possible again?
Next experiment: Keep the architecture map living as the repository evolves.

03 · Operating method

From repository to understanding

The path is deliberate. Analysis is only useful when it becomes something a developer can read, explore, and trust before making changes.

Start from a real repository

Begin with software that already exists—especially systems built quickly with AI assistance, where understanding has not kept pace with construction.

Analyze with AI assistance

Use AI to inspect structure, features, and relationships at a scale that would be slow to do by hand—then shape the result for human reading.

Build a living understanding site

Produce a clear, structured site that explains how the software works. The point is software comprehension, not generating more text for its own sake.

Explore by feature and function

Let developers navigate through functionality, architecture, and relationships so they can find where to work without rediscovering the whole tree.

Understand before you change

Use the map to answer practical questions: what implements this, what depends on it, and what could break if you modify it.

◆

Continue with confidence

Return to development knowing how the application holds together. Understanding is the gate; modification comes after.

Explore Clarify Modify Maintain

04 · Lab principles

How the bench is run

P1
Understanding before modification.
P2
Explain software for humans first.
P3
Explore by feature and function, not only by file.
P4
Keep project knowledge living as the code changes.
P5
Architecture clarity reduces fear of change.
P6
AI assists analysis. Human understanding remains the goal.

05 · The bench

Instruments on hand

The stack stays deliberately practical. The point is not the tools. It is turning a repository into something a developer can understand and continue.

Modest, well understood tools keep the distance short between analysis and a usable understanding site. Shared hosting and familiar runtimes keep each iteration honest about real deployment conditions.

Runtime

PHP 8.2
HTML
CSS
JavaScript

Data

SQLite
MySQL

Automation

Cron workers
GitHub

Delivery

cPanel
Shared Linux hosting

AI assistance

Cursor
ChatGPT
Gemini

Software you built should still make sense

VibeKB is about repository understanding for AI-assisted development. When construction outpaces comprehension, a living understanding site helps developers regain confidence and continue with clarity.

Return to the workshop journal iain@iainreid.dev