thenug.net

keeping docs in git so the ai can read them

March 14, 2026

every piece of infrastructure I run has documentation in a git repo. not because I'm disciplined about it — because it's the only way to make working with an AI assistant actually useful.

the problem

homelab setups accumulate complexity fast. after a few months you have servers running stacks of containers, custom network configs, SSH keys in specific places, volumes mapped to specific paths. it's all in your head until it isn't.

the other problem: Claude Code (the AI I use to manage this stuff) only knows what it can read. if the context lives in your head, the AI is useless for anything beyond trivial tasks. if the context lives in files, it can do real work.

the setup

docs live in a git repo (homelab-docs) on a self-hosted Gitea instance. Gitea is a lightweight self-hosted git server — think GitHub but running on a box in your house.

the repo has a doc for everything:

homelab-docs/
├── README.md           # overview, all servers, external URLs
├── ubuntu-server.md    # server hardware, storage, Docker stacks
├── npm.md              # Nginx Proxy Manager, Cloudflare, external access
├── mediarr.md          # Jellyfin, Sonarr, Radarr, qBittorrent
├── blog.md             # this site — stack, CI/CD, how to write posts
├── syslog.md           # Loki, Grafana, log aggregation
├── gitea.md            # Gitea setup, repos, CI/CD
└── ...

when something changes — new stack deployed, config updated, lesson learned — the doc gets updated and committed. it's version controlled, so there's a history of what changed and when.

how claude reads it

Claude Code loads a CLAUDE.md file at the start of every session. that file points to the docs repo and lists what's in it. when Claude needs to know something — which server a service runs on, what port something uses, how a deploy works — it reads the relevant doc.

this means I can say "add a new post to the blog" and Claude already knows the repo URL, the file structure, how CI/CD works, and what front matter a post needs. no re-explaining every session.

it also means Claude can catch inconsistencies. when I removed Home Assistant from the setup, it searched all the docs for references and cleaned them all up in one go — something easy to miss when doing it manually.

memory files

beyond the docs, Claude maintains its own memory files in ~/.claude/rules/. these cover things that aren't in the main docs:

these get updated automatically as we work. by the next session, the context is already there.

why it works

the key insight is that documentation written for humans is also readable by AI. plain markdown, clear headings, concrete examples. no special format required.

the discipline of keeping docs updated pays off twice: once when you forget how something works six months later, and once every time you ask Claude to do something with the infrastructure and it already has the context it needs.

eli5

every time you set up something new in your house, you write down what you did and why in a binder. when something breaks six months later, you don't have to remember — it's in the binder. when you bring in an assistant (Claude) to help, they read the binder first. now they already know where everything is, which switches do what, and why things are the way they are. without the binder the assistant is basically useless — you'd have to re-explain everything every single time. the binder is just markdown files in git. simple format, but it's the thing that makes everything else work.

← back to blog