--- name: breadcrumbs description: > Create and maintain a `breadcrumbs.md` file — a living design document that lives in a project's root directory and serves as the project's single source of truth for LLM-assisted development. Use this skill whenever: the user starts a new coding project and needs breadcrumbs; the user asks to document, define, or describe their project's architecture or design; the user mentions "breadcrumbs", "breadcrumbs.md", or "project doc"; you're working in a codebase that already has a breadcrumbs.md (read it first, update it as you work); the user asks you to capture design decisions, requirements, or a changelog; or at the end of a coding session when changes should be recorded. Even if the user doesn't mention "breadcrumbs" by name, if they're asking for a project-level design document or want to capture how their project works for future LLM sessions, this is the skill to use. license: MIT metadata: author: bad.download version: "1.0" homepage: https://breadcrumbs.md --- # Breadcrumbs A **breadcrumbs** file is a living design document for a coding project. It sits in the project's root directory as `breadcrumbs.md` and acts as the project's brain — capturing what the project is, why it's built the way it is, and what's changed recently. It's written primarily for LLM consumption, so that any AI assistant picking up the project cold can understand the full picture without spelunking through every file. Think of it as the document you wish existed every time you open someone else's repo (or your own repo from six months ago). ## When to create vs. maintain **Create** a new `breadcrumbs.md` when: - The user is starting a fresh project - You're working in a codebase that doesn't have one yet and the user asks for it - The user says something like "document this project" or "set up breadcrumbs" **Maintain** an existing `breadcrumbs.md` when: - You're working in a project that already has one — read it at the start of the session - You make changes to the project during the session (update the breadcrumbs as you go, not just at the end) - The user asks you to record a design decision or update requirements The goal is that by the end of any session, the breadcrumbs reflect the current state of the project. If you've been maintaining it throughout your work, there's nothing extra to do at the end. ## The breadcrumbs.md structure Below is the canonical template. Not every section is required for every project — use judgment about what's relevant. A one-file script probably doesn't need a Conventions section. But the first five sections (Overview through Design Decisions) are almost always valuable. ````markdown # Project Name Brief one-liner describing what this project does. ## Overview A few paragraphs explaining the project at a high level: what problem it solves, who it's for, and how it broadly works. This is the "explain it to a new team member" section. Write it so that an LLM reading this for the first time has enough context to start being useful. ## Tech Stack - **Language/Runtime**: e.g., Python 3.12, Node 20, Rust nightly - **Framework**: e.g., FastAPI, Next.js, Actix - **Database**: e.g., SQLite, Postgres via Supabase - **Key Dependencies**: the important ones, not every transitive dep - **Build/Deploy**: how it builds, where it runs ## Architecture Describe the high-level structure of the codebase. Where does code live? How do the pieces connect? For a small project this might be a few sentences. For something larger, describe the major modules or services and how data flows between them. Include the directory layout if it helps orient a reader: ``` src/ ├── api/ # HTTP handlers ├── core/ # Business logic ├── models/ # Data models └── utils/ # Shared helpers ``` ## Requirements ### Current What the project needs to do right now. Keep these high-level and outcome-oriented, not task-list granular. Think "the app should authenticate users via OAuth" not "add a login button." ### Future / Planned Things the user has mentioned wanting but hasn't built yet. Capturing these prevents good ideas from getting lost between sessions. ## Design Decisions This is one of the most valuable sections. Every non-obvious choice should be recorded here with its rationale. Format each as a short entry: ### [Decision Title] **Choice**: What was decided **Why**: The reasoning — what alternatives were considered, what tradeoffs were made **Date**: When this was decided (approximately) Examples of things worth recording: - Why SQLite over Postgres (or vice versa) - Why a particular auth approach was chosen - Why the project uses a monorepo vs. separate packages - Why a specific algorithm or data structure was picked - Architectural patterns chosen (and rejected alternatives) When a decision gets revisited and changed, don't delete the old entry — mark it as superseded and add the new decision. The history of *why* things changed is as valuable as the current state. ## Changelog Recent changes go here inline. When this section grows beyond ~20 entries, move older entries to `breadcrumbs_changelog.md` in the same directory and keep only the most recent ones here. ### [Date or Session Identifier] - What changed and why (brief, but enough context to be useful) ## Conventions Project-specific patterns and conventions that aren't obvious from the code alone: - Naming conventions - Error handling patterns - Testing approach - Code organization rules - Anything a new contributor (human or LLM) should know to write consistent code ```` ## Writing guidelines **Write for LLMs, but keep it human-readable.** The primary audience is an AI assistant picking this up in a future session, but humans should be able to read it too. Use clear, direct language. Avoid jargon unless it's standard for the project's tech stack. **Be opinionated, not exhaustive.** The breadcrumbs should capture decisions and reasoning, not catalog every file. If someone needs the full file tree, they can generate one. The breadcrumbs explain *why* the tree looks the way it does. **Keep it current.** Stale breadcrumbs are worse than no breadcrumbs — they actively mislead. When you make changes to the project, update the relevant sections in the same flow. Don't defer updates to "the end" unless the changes are trivial. **Changelog discipline.** The inline changelog should capture meaningful changes: new features, architectural shifts, dependency changes, significant refactors. Not every typo fix. When offloading to `breadcrumbs_changelog.md`, add a note at the top of the changelog section like: "Older entries: see [breadcrumbs_changelog.md](./breadcrumbs_changelog.md)". ## Creating new breadcrumbs When creating breadcrumbs for a new project: 1. **Start by understanding the project.** If there's existing code, read the key files — entry points, config files, package manifests. If it's a brand new project, ask the user what they're building. 2. **Draft the breadcrumbs.** Fill in what you know. It's fine to leave sections sparse — a short document that's accurate is better than a long one padded with guesses. 3. **Call out what you're unsure about.** If you're inferring design decisions from code rather than hearing them from the user, say so: "Based on the code, it looks like X was chosen over Y — is that right, and what was the reasoning?" 4. **Place it in the project root.** The file goes at the top level of the repository, alongside things like `README.md` and `package.json`. ## Maintaining existing breadcrumbs When you're working in a project that has breadcrumbs: 1. **Read it first.** Before doing anything else in the project, read `breadcrumbs.md`. It's your briefing. 2. **Update as you go.** If you add a feature, update Requirements and the Changelog. If you make a design decision, add it to Design Decisions. If you change the architecture, update Architecture. Don't batch these — do them as part of the work. 3. **Don't over-update.** Minor refactors or bug fixes don't always need a changelog entry. Use judgment — would a future session benefit from knowing about this change? 4. **Respect existing voice and structure.** If the breadcrumbs have an established style, match it. Don't reorganize sections unless the user asks. Before ending a session where the project changed, verify: - [ ] The Changelog has an entry for this session's meaningful changes - [ ] New design decisions are recorded with their rationale - [ ] Requirements and Architecture still match what the code actually does - [ ] Nothing in the breadcrumbs contradicts the current state of the project ## Scaling for larger projects For small and hobby projects, a single `breadcrumbs.md` in the root is sufficient. As projects grow, the breadcrumbs can scale in a few ways. ### Sub-component breadcrumbs When a project has distinct modules, services, or packages that are complex enough to deserve their own documentation, break the breadcrumbs into a hierarchy. Each major component gets its own `breadcrumbs.md` in its directory, and the root breadcrumbs becomes an overview that links to them: ```markdown ## Architecture This project has three main components, each with its own breadcrumbs: - [API Server](./api/breadcrumbs.md) — REST API serving the frontend - [Worker](./worker/breadcrumbs.md) — Background job processing - [Shared](./shared/breadcrumbs.md) — Common models and utilities ``` The root breadcrumbs should still contain project-wide information: the overall architecture, cross-cutting design decisions, shared conventions, and the top-level changelog. Sub-component breadcrumbs focus on the internals of their specific piece — their own tech stack choices, internal architecture, component-specific conventions, and local changelogs. **What goes where.** A useful test: if a decision affects how components talk to each other, it belongs in the root. If it only matters within a single component, it belongs in that component's breadcrumbs. When in doubt, put it in the root — it's easier to push something down later than to realize it's missing from the top level. ### When to split A few signals that a project is ready for sub-component breadcrumbs: - **The root breadcrumbs is getting unwieldy.** If a section is longer than the rest of the document combined, that section probably wants to be its own file. - **Different components use different tech stacks.** A Python backend and a React frontend have different dependency stories, conventions, and architectural patterns. Separate breadcrumbs let each speak its own language. - **Multiple people (or LLM sessions) work on different parts.** If the API team and the mobile team rarely touch each other's code, separate breadcrumbs means each session only needs to load the context it actually needs. - **A component could plausibly be its own repo.** If a piece of the project is self-contained enough that you could extract it, it's self-contained enough for its own breadcrumbs. ### Monorepo patterns In a monorepo with multiple packages or services, a natural structure is: ``` my-monorepo/ ├── breadcrumbs.md # Project-wide: shared architecture, cross-service decisions ├── packages/ │ ├── auth/ │ │ └── breadcrumbs.md # Auth service internals │ ├── billing/ │ │ └── breadcrumbs.md # Billing service internals │ └── shared-utils/ │ └── breadcrumbs.md # Shared library conventions └── apps/ ├── web/ │ └── breadcrumbs.md # Web frontend specifics └── mobile/ └── breadcrumbs.md # Mobile app specifics ``` The root breadcrumbs in this case focuses on how the packages relate to each other, shared CI/CD setup, deployment topology, and any decisions that apply project-wide (like "we use pnpm workspaces" or "all services communicate via gRPC"). ### Keeping sub-components in sync When sub-component breadcrumbs exist, the root should include a manifest of where they are. This helps any LLM (or human) discover the full set without searching: ```markdown ## Component Breadcrumbs | Component | Path | Last Updated | |-----------|------|-------------| | API Server | [api/breadcrumbs.md](./api/breadcrumbs.md) | 2026-04-20 | | Web Frontend | [web/breadcrumbs.md](./web/breadcrumbs.md) | 2026-04-18 | | Shared Utils | [shared/breadcrumbs.md](./shared/breadcrumbs.md) | 2026-04-15 | ``` When working in a sub-component, update that component's breadcrumbs directly. If the change has cross-component implications (like changing an API contract), also update the root breadcrumbs and any affected sibling breadcrumbs. ### Changelogs at scale Each sub-component can maintain its own changelog section (and its own `breadcrumbs_changelog.md` for overflow). The root changelog should capture project-level events: releases, major cross-component changes, infrastructure shifts. It doesn't need to echo every change from every sub-component — that's what the sub-component changelogs are for. ## Build exclusion The breadcrumbs contain internal design information that probably shouldn't ship to production. Advise users to exclude them from builds: - **Version control**: Usually you *want* to commit the breadcrumbs — they should travel with the code. But if the project is public and the user wants to keep design reasoning private, they can be gitignored. - **Docker**: Add `breadcrumbs.md` and `breadcrumbs_changelog.md` to `.dockerignore` - **npm**: Add to `.npmignore` if publishing a package - **General**: Add to whatever ignore/exclude mechanism the project's build system uses (most bundlers like Webpack/Vite already ignore `.md` files) When creating breadcrumbs, check if the project has a `.dockerignore`, `.npmignore`, or similar, and offer to add the exclusion. For projects with sub-component breadcrumbs, use glob patterns where supported (e.g., `**/breadcrumbs.md` in `.dockerignore`).