Linked docs example

Context

Some facts are too long for the file that loads on every chat: how the app is shaped, what personal data it collects, and why a trade-off was chosen.

The problem

If those facts live only in a chat, the next chat does not have them. If they are pasted into AGENTS.md, every chat pays for them, including chats that do not need them.

What you do

You keep three short docs and name, in AGENTS.md, the task that should open each one.

What this achieves

A privacy change reads the privacy note. A layout change does not. The reason for a decision is still in the repo next month.

Who reads it

Nothing loads these automatically. AGENTS.md tells the agent when to open each one. That is the point: a privacy change reads the privacy doc, and a layout change does not.

What it is for

Split notes by task. Architecture answers where a feature lives. The privacy doc answers what personal data is collected and how consent works. Decisions records why you chose one approach.

Write them as drafts the team can keep true. The privacy doc is not legal advice.

What goes in

• A module map and the request path in the architecture doc.
• The real list of personal data, consent, erasure, and a named contact in the privacy doc.
• One paragraph per decision, with the date and the folder that implements it.

Sample

# Architecture

One page. Update it when you add a module, route, or data store.

## What this product does

Two or three sentences.

## Modules

- Web app — where it lives, and what it owns
- API or server functions — what they accept and what they store
- Data — which store, and who is allowed to read it

## Request path

Browser, then the server check, then the database. Name the real folders.

# Data and privacy

Draft for a lawyer. Describe only what this product actually does.

## What is collected

- Contact or account fields: list them
- Analytics: off until the person accepts, or not used
- Files people upload: none, unless you build that

## Rules while building

- Consent is an explicit opt-in. No pre-ticked box. The server checks it again.
- Reject leaves analytics, session replay, and ad tags unloaded.
- Fonts are self-hosted unless there is a reason to load them from a third party.
- This product is not for children unless a parent-consent path is an explicit requirement.
- Personal data is not sold. Marketing email needs an unsubscribe path.
- Say where the host may process data, including outside the person's country, if that is true.
- Access, correction, erasure, and withdrawal go to a named email address.

## Not a claim

Do not write that the product is a Significant Data Fiduciary. Do not quote a fine as if it applied automatically.

# Decisions

One short paragraph each. Newest at the top.

## YYYY-MM-DD — Title

What we chose, what we rejected, and why. Link the folder that implements it.

What stays out

• A copy of AGENTS.md.
• A privacy policy that claims fines, ages, or a Significant Data Fiduciary status you have not established.
• Docs that AGENTS.md never links. An unlinked doc is not used, and it still drifts.

Before launch, run the Vibe Coding Security Checklist. These files do not replace that audit. Open the Vibe Coding Security Checklist.