Structuring Project Knowledge for AI-Assisted Development

If you've participated in a well-structured open source project, you know the value of good documentation. The README explains the architecture. Contributing guides define conventions. Style guides enforce consistency. None of this is new.

What's new is that these documents now have a second audience: AI coding tools like Claude Code, Cursor, or GitHub Copilot. And that second audience changes how you should organize the information — not what you write, but where you put it and how you structure it.

This article explains the approach we used in Story Drops, a SvelteKit + Storyblok + TailwindCSS project, and why investing in structured project documentation pays off whether you work with AI tools or not.

The goal: consistency without repeating yourself

Every project accumulates knowledge over time. How components should be structured. Which patterns to follow. Where data fetching happens. How styling works. What the integration with an external service looks like.

This knowledge usually lives in the heads of the developers who built it. A new developer joining the project absorbs it through code review, pair programming, and trial and error.

The problem isn't that the knowledge doesn't exist — it's that it's not accessible at the moment you need it. When you're creating a new component, you need to know: what fonts do we use? What's the spacing convention? How do I make this editable in Storyblok? Where do I register it?

If you use an AI assistant for coding, this problem gets sharper. You can't pair-program with it for a week. It starts fresh every conversation. It needs the context upfront, or it falls back on generic patterns that may not fit your project.

The solution is the same one open source projects have used for years: write it down. But write it down in a way that's structured for reuse — by humans, by AI tools, and by your future self starting the next project.

Two layers: CLAUDE.md and Skills

We use two types of documentation files, each with a different scope:

CLAUDE.md — the project overview

CLAUDE.md sits at the root of the project. Claude Code reads it automatically at the start of every session. It's the equivalent of a senior developer giving you a 10-minute walkthrough on your first day.

It covers:

Stack and tools — not just names, but how they're used. "TailwindCSS v4, utility-first, no custom CSS." "SvelteKit with Svelte 5, TypeScript, bun as package manager."
Project structure — where things live, what each directory is for, naming conventions.
Design system — color tokens, typography scale, spacing patterns, card styles. Concrete enough that any new component matches the existing ones.
Architecture rules — which component owns the layout container, where data fetching happens, how routing works.
Boundaries — what NOT to do. Don't add padding to child components. Don't hardcode content. Don't install libraries outside the stack without a reason.

Here's a concrete example. In Story Drops, the Page component owns the container and vertical rhythm:

Page.svelte provides: max-w-3xl, horizontal padding, vertical padding, space-y between bloks
Child bloks provide: only their internal layout
Standalone pages (Article, ArticleCategory): own their own container

This is the kind of information that prevents inconsistencies. Without it, each new component invents its own spacing. With it, every component follows the same system.

Skills — deep reference for specific domains

CLAUDE.md gives the big picture. But some areas of the project need deeper, more detailed documentation. That's what skill files are for.

In Story Drops, we have two skills:

** .claude/skills/storyblok-integration.md** — everything about how this project integrates with Storyblok. The API client, the bridge for live preview, the component registry, the editable action, the rich text renderer, the routing system, data fetching patterns, and a list of specific gotchas.

A styling/design skill could cover: the complete color token table, every component pattern (cards, buttons, badges, prose), responsive breakpoint conventions, and how TailwindCSS v4's @theme is configured.

The key distinction: CLAUDE.md says "we use TailwindCSS with these color tokens and this typography." The skill file says "here's the exact class combination for every card variant, here's how the prose plugin is configured, here's the responsive pattern we follow."

A note on styling in the markdown. Story Drops is a small project — a bit more than a personal blog. For this scale, defining color tokens, typography, and component patterns directly in the CLAUDE.md and skill files works well. In a more structured project, these definitions would live in a proper design system or pattern library — a Storybook, a Figma-to-code pipeline, a shared component package. The concept stays the same. The skill files don't replace the design system; they explain how to use it in this specific project. "Our pattern library defines a CardBase component — here's when to use it, here's which variant to pick for article listings, here's how spacing between cards is handled." The source of truth for the design lives where it belongs. The skill file bridges the gap between that source and the daily work of building with it.

What goes in each file

CLAUDE.md should answer:

What's the stack?
Where do files go?
What are the project-wide conventions?
What's the design system (tokens, typography, spacing)?
What should never be done?

A skill file should answer:

How does this specific integration work in detail?
What are the API patterns and parameters?
What are the concrete code examples?
What are the gotchas someone would discover only after debugging?

Why this matters — beyond AI tools

Let's be clear: this is not just about AI. This is about project knowledge management. The same documentation that helps Claude Code write consistent components also helps:

A new developer joining the project and creating their first component
You, six months from now, coming back to add a feature and not remembering the spacing conventions
A new project, where you can copy the skill files as a starting point and adapt them

If you've ever started a new project and thought "I solved this exact problem before, but I don't remember how" — that's the problem structured documentation solves.

The difference with AI tools is efficiency. A human developer reads the docs once and builds intuition. An AI tool reads the docs every session and follows them literally. This means:

Ambiguity hurts more. A human interprets "use Tailwind" based on experience. An AI might use arbitrary classes. Write font-serif text-3xl font-extrabold tracking-tight text-brand-ink and it uses exactly that.
Omissions compound. A human notices that all other components use rounded-xl and follows the pattern. An AI doesn't browse the codebase for conventions unless told to. Write it down once and it applies everywhere.
Repetition disappears. Without docs, you explain the same convention in every prompt. With docs, you say "add a new component" and the AI already knows the conventions, the tokens, the structure.

A practical example: creating a new component

Without structured documentation, adding a new Storyblok component requires a prompt like:

"Create a new FeaturedArticles component. Put it in src/lib/components/storyblok/. Register it in components.ts with the key 'featured-articles'. Use storyblokEditable on the root element. Use font-serif text-3xl font-extrabold for the title. Use the brand-accent color for hover states. Don't add padding — Page.svelte handles that. The articles field is a relation, check if it's resolved..."

With CLAUDE.md and skills in place, the same request becomes:

"Create a new FeaturedArticles component for the featured-articles blok. It has title (text), description (richtext), and articles (multi-option stories relation)."

Everything else — the file location, the registration, the editable action, the styling, the spacing, the relation handling — comes from the documentation automatically. The prompt is shorter because the context is already there.

Structuring for reuse across projects

One of the strongest benefits is portability. The skill files are project-specific, but the structure is reusable.

Starting a new SvelteKit + Storyblok project? Copy the Storyblok integration skill and adapt it. The sections stay the same — API client, bridge, component registry, routing, data fetching, gotchas — but the implementation details change.

Starting a new project with TailwindCSS? Copy the design system section from CLAUDE.md and update the tokens.

Over time, you build a library of well-structured project knowledge that makes each new project faster to set up — not just the code, but the documentation that keeps it consistent.

Getting started

You don't need to write everything at once. Here's a practical sequence:

Create CLAUDE.md with your stack and structure. List the framework, language, styling, CMS, package manager. Define where files go. This takes 15 minutes and immediately improves every AI interaction.
Add your design system. Color tokens, font choices, heading scale, spacing conventions. Be specific — use the exact Tailwind classes, not descriptions.
Add "do not" rules as you discover them. Every time the AI (or a developer) does something that doesn't fit the project, add a rule. These accumulate into a valuable set of guardrails.
Extract skills when a domain gets deep. If you find yourself explaining Storyblok conventions or TailwindCSS patterns repeatedly, move that knowledge into a dedicated skill file.
Keep it versioned with the code. CLAUDE.md and skill files live in the repo. When the code changes, update the docs in the same commit. No external wikis, no Notion pages that drift out of sync.

What this is really about

This isn't about AI. It's about treating project knowledge as a first-class artifact — something you design, maintain, and version alongside your code.

Open source projects have done this for decades. Contributing guides, architecture decision records, style guides — they all serve the same purpose: giving someone (or something) enough context to contribute consistently without absorbing years of tribal knowledge.

The rise of AI coding tools just made the cost of not doing this more visible. When every conversation starts from zero, the value of structured, accessible project knowledge becomes obvious.

Write it down. Structure it well. Your future self — and your AI assistant — will thank you.