Documentation Strategies - Harness engineering: Leveraging Codex in an agent-first world

In-repo docs, static websites with clickable sections, work logs, condensing stale documentation, agents updating rather than appending docs

Modern documentation strategies are shifting toward agentic, in-repo systems where AI maintainers prioritize updating existing content over merely appending logs to maintain a cohesive and accurate project history. To keep these agents efficient, developers recommend condensing stale files and utilizing clickable static sites to optimize context windows, ensuring the AI can track historical reasoning without being overwhelmed by redundant data. While concerns persist regarding potential "blindspots" created by massive markdown archives, the emerging consensus favors using these work logs alongside automated testing to transform documentation from a passive record into an active, reproducible framework for validation.

View on HN · Topics

This mirrors exactly what I have been doing.

- Give Claude/Codex a way to verify its own work (browser, smoke tests, e2e tests, high-fidelity local environment)

- Keep all context (issue tracking, docs, ideas, plans, worklogs) in-repo ( https://github.com/shepherdjerred/monorepo/tree/main/package... )

- Give Claude/Codex access to observability (Grafana, Prometheus, Tempo, PagerDuty)

- Have Claude/Codex follow good engineering guidelines like fail-fast, type safety, parse at boundaries

I haven't yet been able to achieve full autonomy due to cost and CI load on my homelab.

View on HN · Topics

Does it yield good results?
I found that instead of docs it’s easier just to ask ai to read code.
I feel like this is same as comments in code. Become outdated fast

View on HN · Topics

I don't really use "docs" for documentation. I've prompted Claude/Codex to always write a "log" and save it in-repo to track what it did and why.

I've found this to be really helpful, e.g. "you did this last week, and now some other thing is happening" or "you tried this approach before to solve alert X but it didn't work" -- except it can discover this itself.

https://github.com/shepherdjerred/monorepo/tree/main/package...

I've also used it to store TODOs and plans. For example I might want to explore some idea and defer it for later, or some weekend have it execute on some tech debt I've put off. One last use case is asking "what did I work on in the last 2-3 weeks, is it healthy, and what additional quality checks can/should I do; is there any follow-up work?"

View on HN · Topics

I like the idea of saving the work done into files - helps to prevent the llm from redoing the same work. Maybe one day instead of code in a repo it will just be a list of prompts.

View on HN · Topics

I worry most about blindspots with this kind of approach. Let's say that this repository goes on for years, at which point the docs folder is several MB in size. Would Codex be able to think outside of the box? Or would the aggregate of the Markdown content fundamentally cover enough ground to prevent it from thinking of novel new approaches to existing problems?

View on HN · Topics

You tell it to update the docs: not append. I've done the same thing with a readme in the root with links to the docs. After every commit, before the push, I have my agent "update all relevant and related docs, add or remove what's needed" or something to that extent. And it works remarkably well. I also have an append only change log it's supposed to add to. Between that, good commit messages, and comprehensive testing, I've built a homebrew OS and updating it is remarkably smooth. Runs a homebrew FTP and HTTP server and can run Wolfenstein. Working on DOOM right now. Close, but sound has been difficult.

https://github.com/ESikich/smallos

View on HN · Topics

Someone else in the comments said to have it make a static website with the info instead with clickable pages and sections so it reads only the content it needs to rather than dumping a long file into context windows. Although I suppose you can have a ToC in the readme too with multiple smaller markdown files as references.

View on HN · Topics

Yep. You’ve got to have it update the docs. After a few sessions, if I forget to request this, opus starts rehashing the same tasks and finds that they are complete - and sometimes still won’t update those docs unless I ask.

Another tip is to condense the doc files into the minimal required. Sometimes I’ll end up with 5 to 6 floating around in various states of staleness. Condensing to 2-3 and removing completed tasks seems to help a lot

View on HN · Topics

This is the part I think we will see become more relevant.

I created docs-cli (pypi) to manage the index of specs as source code: the framework that goes with it will first create tests for as much as it can, so reproducability becomes the goal, not readability.

https://github.com/ArtRichards/docs-cli

https://artrichards.github.io/agent-playbook-suite/blog/

View on HN · Topics

Everyone is criticizing the number of lines of code and the lack of attention that must certainly have been applied to generate that code and push it into production. What is being ignored is this awesome prompt that is almost certainly better than having no agents.md or plans.md or whatever you've come up with, to add validation steps for committed changes. You're still free to look at your code, the changes, and ask the agent to clean up. Try it. It's really nice.