specs.md isn't a rigid spec document. It's a living one.

September 10, 2026

This article is a look back at how I handled documentation on the Diet App project, the nutrition tracking app I built with Claude Code (see the full case study for context on the project).

It all started with specs.md, the very first file, born out of a brainstorm with Claude AI before I even had an empty app on my machine. What I hadn't anticipated at the time is that it would drag about ten more files behind it. They didn't all show up at once, following some documentation plan laid out in advance. Each one appeared exactly when I actually needed it, when moving forward without it started costing too much in confusion or in unnecessary back and forth with Claude Code.

This isn't an attempt to sell some ideal documentation architecture to copy before you start. It's a look back at what showed up, when, and why, and at what it changed in how I steered Claude Code batch after batch.

The first file: specs.md, before the code

The project's first file, specs.md, didn't exist before a brainstorming session with Claude AI. The starting idea was simple. Turn the Google Sheet I'd used for years to track my nutrition into a real mobile app. I shared the CSVs exported from that sheet, described the expected features and the UX behaviours I wanted, and Claude AI helped me arbitrate priorities and set the MVP's scope.

That session produced two deliverables. A FigJam flowchart with the main screens, the navigation flows and the key behaviours of each view. And specs.md, meant from the start to become the project's source of truth.

Its first section isn't addressed to me. It's addressed to Claude Code directly. Which language to use, naming conventions, and the rule that takes precedence in case of conflict with the project's other documents. Putting these instructions first frames everything else before even getting into the actual content.

Next comes the app's overall architecture, tech stack and target file structure, then every MVP screen detailed one by one. Onboarding, profile setup, diary, food, recipes, profile. For each one, the expected layout, the blocks, the behaviours, down to the edge cases. The Supabase data schema and the calculation rules come next, along with a first version of the design system. The file ends with a section of notes addressed to Claude Code, to frame what was still open when launching the first batch.

That structure was anything but incidental. It gave Claude Code a full context before writing a single line of code. That's what made the split into twelve sequenced batches possible.

But specs.md didn't stay frozen at that starting state. Over the twelve batches, it grew, got more precise, got corrected, as decisions were made during the build. What had started as a launch brief became, over time, real in-depth technical documentation, the project's source of truth and the file that holds the richest context Claude Code consults.

The first batch ships, the stack gets dense: documentation.md

documentation.md came later, once the project's foundations were in place. Dependencies installed, Tailwind configured, tokens in place, first Supabase migrations run. The day I needed to clarify the role of every tool and framework in the stack, instead of keeping them scattered in my head: React, React Native, NativeWind, Metro, Expo, expo-router, TanStack Query, Zustand, Supabase. The project structure folder by folder, the build and test procedures on my iPhone. The file was built up gradually, following the clarification needs that came up during the build.

This content never belonged in specs.md, which stayed focused on the product vision, the screens and the expected behaviours. Nothing to do with how the stack works internally or with code conventions.

Once in place, it became the reference I still check today to find a build procedure or check a convention, and the one Claude Code consults to understand how the project is organized.

The design system work spins up three files at once

The design system work spun up three files at once: design-tokens-architecture.md, design-system-rules.md, component-map.md.

Unlike specs.md and documentation.md, which each cover a broad domain, a single file wouldn't have been enough here. Each of these three answers a different question.

design-tokens-architecture.md documents the three-layer token architecture, primitives, semantic aliases, component tokens, and the one-way flow rule between them.

design-system-rules.md condenses the concrete styling rules, the color, typography and spacing values, and the critical rules to follow in every component.

component-map.md links Figma to the code, which Figma component maps to which source file, which props, which usages. This file has its own backstory. Figma offers Code Connect to automatically link Figma components to code, but it's only available from the Organization plan, out of reach for a solo project. component-map.md is the substitute I built by hand to make up for that, an exhaustive mapping maintained manually rather than automated.

Keeping these three files separate instead of merging everything into one keeps it from turning into a catch-all. Token architecture, styling rules, Figma mapping, these are three different kinds of content, with different update rhythms. Tokens rarely move once set. Styling rules evolve with every new component. The Figma mapping gets updated at every generation or correction session in Figma.

The Figma MCP workflow demands its own files

The Figma MCP workflow spun up two more files, figma-prompt-template.md and figma-etats-manquants.md. They showed up once the back and forth between Figma and the code became a regular practice instead of a one-off.

figma-prompt-template.md answers a precise need, a reproducible prompt format for every UI update coming from Figma. The exact Figma frame to target, the file to edit, the changes to implement, the constraints to respect, linking an existing variable rather than setting a raw value, attaching a screenshot alongside the link. A standardized format, so nothing gets forgotten from one session to the next and the same rigor holds for every update. Depending on how it's used, this file could eventually become a skill in its own right rather than a simple template to copy and paste.

figma-etats-manquants.md answers a different need, keeping a clear picture of what exists on both sides, in the Figma library and in the code. An inventory of screens, states, interactions, with the gaps between the two. A cross-audit that serves as a starting point whenever there's a need to iterate on a specific state, in either direction.

These two files aren't the same kind as specs.md, documentation.md or the design system files. They're not specs. They're tracking files. They don't settle anything definitively, they describe a state at a given point in time, with their own update rhythm, tied to every Figma session rather than to every structural decision.

Closing out a version: audit.md, backlog.md and the ADRs

audit.md, backlog.md and the ADRs didn't show up at the same time.

The audit practice started early, right at the end of the first batches. No skill yet at that stage, I'd ask Claude Code directly to run an audit, specifying each time what needed checking. It wasn't until after v0.1, once the twelve batches were done, that this practice turned into a proper skill, /audit, able to regenerate audit.md without me having to rephrase the request every time.

Once the skill was in place, audit.md became a snapshot never edited by hand. Strengths, weaknesses ranked by severity, a priority table, issues resolved since the last pass. A picture of the code's real state at a given moment, overwritten and replaced with every new audit.

backlog.md and the ADRs both showed up at the same time, at the v0.1 milestone. At that point I looked into documentation best practices, beyond the README.md and CHANGELOG.md files I already knew about. That research is what brought ADRs into the project.

backlog.md captures what's deferred. Tasks ranked by priority, watch points to check on future version bumps, deferred decisions. A way to properly close out a version without losing track of what's still waiting.

ADRs log something else, the why behind decisions already made. Like why the project is single-user, with no authentication. Or why macros are never stored but always recalculated. Each entry fixes the context, the decision, and what was ruled out. Without these files, the risk is questioning a decision again later, with no trace left of the reasoning that drove it.

That research taught me something beyond the ADRs themselves. Documenting a project's technical side and its states isn't enough. Documenting the choices, the why behind every decision, matters just as much.

The number of files grows, and they need to stay maintainable

At this stage of the project, the question wasn't just about writing documentation anymore. It was about keeping it up to date and consistent with the code's actual state, without redoing everything by hand each time. The docs/ folder already covered the specs, the tech stack, the design system, Figma tracking, the audit, the backlog, the ADRs. Manually checking that each of these files still reflected the project's reality was becoming unsustainable.

Two concrete answers to that problem. The /docs-update skill, a systematic pass that goes through the docs/ folder document by document to check that each file is still up to date. And the regular audit cadence, driven by the /audit skill, which regenerates audit.md on every run with no manual work.

Neither of these skills would be worth much without a mechanism that makes the files easy to consult. CLAUDE.md, at the root of the project, declares the reference files Claude Code should consult. Once these files are declared, they're picked up automatically in every session, with no need to mention them again in every prompt. Other skills got added to this base over time, /lot to generate a structured batch plan, /debug-error to structure the debugging process.

Takeaways, limits, ideas for improvement

Looking back, several limits stand out.

The first one is already flagged in my own backlog. design-system-rules.md keeps growing with the project, a file that gets longer as new components and new rules get added to it. The idea on the table is to move to path-scoped .claude/rules/ if the file gets too heavy to read in full. Not decided yet, but the signal is there.

The second is about discipline itself. Not every file gets regenerated automatically like audit.md. component-map.md, figma-etats-manquants.md, and others, depend on me to stay in sync with the actual state of the code or the Figma library. And it has happened to me, on several files, not just those ones. The /docs-update skill has made things better, a systematic pass beats a random check. But there's probably still room to make the whole thing more reliable, instead of relying on my own vigilance alone to catch drift.

The third is about backlog.md itself. The file mixes several kinds of content under one roof. Prioritized tasks, a watch section tied to future events like version bumps, and one-off technical notes surfaced by /audit. It's exactly the kind of situation that led to three separate files for the design system. backlog.md has never been split the same way, even though it carries several different roles.

That last point opens up another one. /audit today just regenerates audit.md. A concrete improvement would be for it to go further, start a dialogue, a few questions to prioritize the detected tasks, and feed them directly into backlog.md instead of leaving me to sort that out by hand every time.

More broadly, after piling up all these files and skills, a question starts to surface. The question of a real documentation architecture, instead of an accumulation of files added one by one. You start to see the point of more holistic documentation, one that would connect the technical, the functional and the design instead of keeping them in separate files that only talk to each other through me. A longer-term idea. Not a real project yet, but it's starting to take shape.

Conclusion

As many files as there were different moments in the project. None of them existed before I needed them, and none showed up according to some plan I could have written in advance. The skills themselves only came once the maintenance load got too heavy to stay manual.

What I take away from this isn't so much the list of files as the rhythm in which they appeared. specs.md set the vision before the code. documentation.md set the stack once it actually existed. The design system needed three separate files the day strict consistency became necessary. The Figma workflow needed its own the day the back and forth became routine. audit.md, backlog.md and the ADRs closed the first cycle by documenting not just the state of the project, but also the choices that led there.

And the last part of this article makes it clear, this construction isn't finished. Some files keep growing, others still depend too much on my own vigilance alone, and the question of a real documentation architecture, rather than a stack of files added one by one, is just starting to surface.

If this piece is useful for anything beyond my own project, it's probably that. Let documentation grow out of real need instead of designing it upfront in a vacuum, while accepting that it will keep demanding work as it grows.