4.1.2 - If the Secret Only Exists on Your Machine, You Are the Single Point of Failure

Decide where secrets live and how they are set per environment, with every name the code reads written down and no real value anywhere near it.

Secrets

If you lost your laptop tonight, could anyone else bring this up tomorrow?

The call

List every name the code reads and say where the value for each one lives in each environment. Never the value itself.

Sharpen secrets with AI

This is a Run idea, so the AI move is Run it for real. You can sharpen the decision here, but it only proves out against a system that is actually live.

New here? Let your AI do this with you. Paste your problem into Guide me and it builds a prompt that walks you through this in ChatGPT or Claude. You do not need to know how to prompt.

Prefer to drive the AI yourself? Give ChatGPT or Claude this page and ask it to help. For skill.txt, the Claude Code plugin and other ways in, see how to use vibe2value.

Or copy this prompt into AI chat, replace the bracketed lines with your real keys and keep the instruction exactly as visible here. It helps you put your secrets.md together by refining your three lines until somebody who did not build this could act on them.

You are checking whether this secrets plan is clear enough before you move forward.

Constraint:
A new person must be able to get the project running from what is written, without anyone handing them a value privately. Every name the code reads appears in the list. No real value appears anywhere in it.

Example of the standard:
Vague: "Secrets are in the environment and in the deploy settings."
Sharp: "The code reads three names: the mail key, the store key and the model key. Locally they come from .env, which is gitignored and mirrored by .env.example with empty values. On develop and main they are set in the platform's own secret store and two people can read them. Rotating one means changing it there and redeploying, because nothing picks it up at runtime."
The sharp version names every key and where its value lives per environment. The vague one names neither.

Working draft:
Names the code reads: [every one]
Where the value lives per environment: [local, plus each deployed environment]
How a new person gets set up: [the actual steps]

Task:
Decide whether a new person could get running from these three lines without being handed a value privately. Check that every name the code actually reads appears. If a real value has been written down anywhere, say so, because that is the thing to fix first.

Check:
- Does the code read a name that is not on the list?
- Is there a real value written into any file that is tracked?
- Can you say who is able to read each value? Can you say how one gets rotated?

Return:
- Verdict: clear, or needs work
- The corrected three lines
- Any name the code reads that is missing. Any real value that should not be there

Copy this into AI chat. Replace the bracketed parts. Keep the rest unchanged. AI will likely suggest refinements based on what you enter. Use those to sharpen your thinking, not replace it.

Where the values live follows from where the thing runs, which is Where the code runs. The wider set is ways to run it for real.

The same idea on a recipe card

Every kitchen has the supplier list on the wall. It says what to order and who from. It never says the card number.

When the head chef is away the kitchen still opens, because the part everybody needs is written down and the part nobody should have is not. Those are two different decisions and most people only make one of them.

The recipe card is just a simple example, using everyday cooking ideas everyone understands, to make the concept clear. See the recipe card.

What it really means

Two failure modes pull in opposite directions here, which is why this one is easy to get wrong in both directions at once.

Write a value down and you have leaked it, permanently, into a history that is hard to clean. Write nothing down and the project can only be run by whoever already has the values, which is usually one person, usually you.

The way out is that the two halves separate. The names the code reads are documentation and belong in the file. The values are secrets and belong in the platform. A file that names every key and where its value lives is safe to read and enough to work from.

Make secrets concrete

Compare the version that sounds responsible with the version somebody could act on.

Too vague: Secrets are in the environment and in the deploy settings.
Concrete enough to act on: The code reads three names: the mail key, the store key and the model key. Each one lives in the platform's own secret store, set per environment and never on my machine. A new person registers, confirms the address they will send from and sends one line.

The second version is something a new person can act on. There is still no secret in it.

Both versions come from consideredContent, the one project carried through all 35 ideas. See the project.

There are three answers and only the middle one works. Put the values in and they are in the history forever. Put nothing in and only the person holding them can run it. Put the names in, with where each value lives, and a new person gets running without anything leaking.

Check secrets

Pass: A new person can get the project running from this file without being handed a value privately. Every name the code reads appears here.
Fail: A real value has been written into this file, or the code reads a name that nobody has listed.

A secret only you can reach is not security. It is a bus factor of one.

What you'll walk away with

This post is about the running decision: what has to be true once the thing is already live. You'll come out with your own knowledge-base/system/environments/secrets.md written and sharpened: every name the code reads, where the value for each lives per environment, who can read it, how it gets rotated and the steps a new person follows to get running.

Write it down

Your secrets.md is a real file in your project. The AI forgets everything between sessions. It reads this file each time to pick up what you already decided, on this idea or another part of the build. Write it down once instead of explaining it again.

knowledge-base/system/environments/secrets.md is just a suggested name and place for this information. Call the file and put it wherever suits your project. What matters is that it is written down in a format that is easily understood by both people and the AI.

Risk and mitigation

Risk: You are unavailable and nobody can bring the project up, or a real value reaches the repository and has to be rotated in a hurry.
Mitigation: Keep the names and locations in the file and the values in the platform. Add an example file with empty values so nothing has to be guessed.

Key takeaway

Write down every name the code reads and where its value lives. Never the value.

How to document your secrets

Write it up in full so your AI has the whole picture: the answer, why you believe it, what you are optimising for, where you might be wrong and the standing instruction it should follow. Keep it in a file with your project like this.

# Secrets

## Answer
Names the code reads: [every one]
Where the value lives per environment: [local, plus each deployed environment]
How a new person gets set up: [the actual steps]

## Evidence
What the code actually reads, checked against the code rather than remembered.

## Decision
Who can read each value and how one gets rotated.

## Risk
What breaks if this is wrong.

## Standing instruction
What the AI should do every time it touches this. For example: if you add code that reads a new name, add it to this list in the same change. Never write a real value into any tracked file.