diff --git a/README.md b/README.md
new file mode 100644
index 0000000..0dc1510
--- /dev/null
+++ b/README.md
@@ -0,0 +1,25 @@
+# AoC2023
+Advent of Code 2023
+
+## Repo structure
+```bash
+> tree
+.
+├── inputs
+│   └── 00_moelf.txt
+├── solutions
+│   └── 00_moelf.txt
+└── src
+    ├── cpp
+    │   └── 00.cpp
+    └── julia
+        └── 00.jl
+```
+
+- the input files should be named as `<day>_<name>.txt`, the content should be the input of the day without any dangling empty lines at the end
+- the solutions files should be named exactly as corresponding input file, the content should be exactly one or two lines (depending on if you solved both parts)
+- the `src/<lang>/<day>.<ext>` should matched the double-digit day number convention. The `<lang>` should match what appears in [`runtests.jl`](https://github.com/Moelf/AoC2023/blob/86fd788cfd96334194b1f9defb096824eaa7776f/runtests.jl#L16-L25)
+
+## How to contribute
+- upload input and solutions in the same PR. Name and clean up them properly
+- when adding a new programming language, remember to update `runtests.jl` to "teach" it how to compile & run the `<lang>`