README.md is that one file in every project that gets the princess treatment from GitHub, GitLab, and other source code hosting platforms. It is displayed gloriously at front of every project page. IntelliJ even casually opens it the moment you import a new project, while it goes off indexing the tech debt— err, codebase.
But, when did you last update your README.md? Was it created during project's genesis and the last commit message there is still "initial commit"? Did it come bundled with the project starter template and remains untouched ever since?
When it comes to personal side-project repositories, I am guilty of this too.
I usually include the bare minimum—just enough for me to remember what commands to run, plus a few references
so that I don't have to go down hunting my terminal's history with history | grep xyz when (or if) I reopen
it back months later. Handovers would be messy.
It is 2024—no, wait, 2026. The world has finally picked up its pace after the pandemic slowdown. Everything is moving fast... except README.md.
So today, if you're getting onboarded to a new project, the best place to start is probably no longer just the README.md file—it's the AGENTS.md, or one of its equivalents—GEMINI.md, CLAUDE.md, etc. as well. These files often contain almost in-detailed explanation of the project, structure, coding styles guidelines, and more. Turns out, humans have to get more thorough when explaining things to machines. And they have to, in order to get the best out of the agents.
Here is a brief GEMINI.md file for a side-project I started a couple of days ago. I keep revisiting it—adding, removing and polishing it to make Gemini work effectively with my codebase. And I bet it will grow with time.
...
## Project Stack
- **Language**: Kotlin
- **UI**: Compose Multiplatform with Shared UI
- **Architecture**: Unidirectional Data Flow (UDF)
- **Concurrency**: Kotlin Coroutines
- **Build**: Gradle (Kotlin DSL)
- **Dependency Injection**: Koin
...
## Code Instructions
- Prefer `Modifier` parameters first
- Prefer named parameters.
- Use **Material3 color scheme**
- Do NOT hardcode colors in composables. Reuse existing colors defined in Theme.kt file.
- Prefer single source of truth
...
- Expose `StateFlow<UiState>`and UI events via sealed classes.
- Every private `StateFlow` will have corresponding `MutableStateFlow` exposed to UI layer.
Another good place to check is the package management files—build.gradle, package.json, requirements.txt, and the likes.
These help you understand the internal dependencies used in the project. For external dependencies, docker-compose.yml is your guy.
You can hit the ground running with these.
And if you're struggling to build and run the project—or just want to know where/how/when it is deployed, the CI/CD pipeline files—like .gitlab-ci.yml, .circleci/, .github/ contain literal step-by-step instructions, if you squint hard enough.
Instructions meant for machine are clearer than those meant for humans. And that's the place to start.