Most failed projects have tests. Almost none of them have context.
The difference between a project that survives its creators and one that dies the moment they leave is not the quality of the code. It is the quality of the memory.
⸻
The Front Door
A project without a README is a building without an entrance.
People stand outside. They guess. They open random files. They make assumptions that contradict other assumptions made by the person who guessed yesterday.
Five questions. That is all a README needs to answer: What does this do. Why does it exist. How do I run it. Where does everything live. Who is it for.
If the front door is locked, nobody comes in. If nobody comes in, the building rots from the inside.
⸻
The Reason, Not the Change
Commit messages capture what happened. They do not capture why.
"Fixed the learnings bug" is a fact that expires in two weeks. "Fixed the learnings bug because ChromaDB rejects list metadata, must convert to comma-separated strings" is institutional memory that saves hours six months later.
A changelog that records only the what is a receipt. A changelog that records the why is a decision log.
One gathers dust. The other compounds.
Keep it at the root. Newest first. Timestamp every entry.
⸻
The Same Question, Asked Forever
Teams ask the same questions in perpetuity. Not because the answers are hard, but because the answers are never written down.
Every question asked and answered should be recorded. Categorized. Searchable.
An FAQ is not documentation for beginners. It is a circuit breaker for repeated work.
Without it, every new contributor, human or machine, starts from zero. The system forgets what it already knows.
⸻
The Invisible Backlog
Work that lives only in someone's head is work that has already been lost.
Unfinished tasks. Known limitations. Technical debt. Feature ideas.
These are not reminders. They are the real state of the system.
When they are invisible, people duplicate effort. They build on top of problems they do not know exist. When they are visible, they become a shared map of what is true.
A file at the root. Checkboxes for status. Most impactful work at the top. Simple. Effective. Rarely done.
⸻
The Documentation Decay
"We'll write the docs after we ship."
No, you will not. You will ship, then move to the next feature, then the next fire, then the next quarter, and the documentation will remain exactly as stale as it was when you made that promise.
Documentation written from fresh memory costs two minutes. Documentation reconstructed from cold code costs two hours of archaeology.
The only documentation that stays accurate is documentation updated in the same session as the change. Everything else is a guess wearing the uniform of a source of truth.
⸻
The Unverified Ship
Every unverified change is a bet.
You are betting that your mental model of the system is correct. You are betting that nothing else depends on the thing you just touched. You are betting that the thing you did not test is the thing that will not break.
A thirty-second test run catches what a thirty-minute production debug will eventually find anyway.
Run the tests. Check the feature end-to-end. Confirm nothing else broke. Automate what you can. Document what you cannot. But never ship on faith.
⸻
The Hardcoded Secret
An API key in source code is a timer.
It will be committed. It will be pushed. It will be exposed. Not if. When.
Configuration belongs in the environment. Secrets belong in vaults.
Ship a .env.example with placeholders so anyone can see the shape of what is needed without touching the live wires.
Hardcoded URLs break on the second deployment. Hardcoded secrets break trust on the first.
⸻
The Blind System
You cannot fix what you cannot see.
A system without logging is a system that reports "it's broken" and nothing else. A system with logging reports "the Gemini API is rate-limiting every 50th call at 3AM on Tuesdays."
One is a complaint. The other is a solvable problem.
Log decisions, not just errors. Track state transitions, not just crashes. Normalize failures into categories so patterns surface instead of noise.
Observability is not a feature. It is the difference between operating a system and being operated by one.
⸻
The System That Never Learns
A system without feedback makes the same mistake on day one thousand that it made on day one.
Capture what happened. Record why it worked or why it did not. Feed the past into the future. Let the human correct what the machine cannot see.
The distance between a tool and something resembling intelligence is the feedback loop. Without it, you are not iterating. You are repeating.
⸻
The Missing Map
An undocumented architecture is an invitation for every new contributor to build a different building.
They will make assumptions. Those assumptions will conflict. Six months later, half the system follows Pattern A and the other half follows Pattern B, and nobody remembers who chose either.
Document the components. Document the data flow. Document the key decisions. And document what not to do, the anti-patterns discovered the hard way, so they do not get rediscovered.
Update the map as the terrain changes. A stale map is worse than no map. It does not just fail to help. It actively misleads.
⸻
The Terrain
Every project root should contain:
README.md: the front door.CHANGELOG.md: the decision log, newest first.FAQ.md: the circuit breaker.TODOs.md: the visible backlog..env.example: the configuration shape, no secrets.docs/: the map.
And every workflow should include:
- Update documentation with every change.
- Verify before shipping.
- Make the system observable.
- Close the feedback loop.
These are not best practices. They are the minimum conditions for a project to survive contact with reality.
⸻
End.