Ask HN: How is your team changing documentation for AI-assisted coding?

Posted by hubraumhugo on Monday March 02, 2026 @10:20AM
from the ask-hn dept.

The thread on whether AI sessions should be part of the commit (https://news.ycombinator.com/item?id=47212355) got me thinking about documentation more broadly. How do you document when agents write most of the code?

Specs and intent docs (plan.md, Linear ticket, change records) seem to become more important since they're what agents work from. On the other hand, the traditional RFC/architecture docs drifts out of sync faster.

How are you adopting your documentation workflows internally? How do you get feedback on specs before implementation?

( 2 comments | 3 points | on HN )

Re:Ask HN: How is your team changing documentation for AI-as... by guerython on Monday March 02, 2026 @10:24AM (#47219143)

plan.md now drives everything. we keep a tiny intent doc per agent run, surface acceptance tests, and block merges until a reviewer signs off so specs get upfront feedback before the agent runs. what review hooks do you use to keep the plan doc manageable?

[ Parent | on HN ]

Re:Ask HN: How is your team changing documentation for AI-as... by jumpalongjim on Tuesday March 03, 2026 @03:48PM (#47238744)

I find that communicating with AIs is enhanced by using Mermaid diagrams, which the AIs love to write and can convey quite a lot of complexity in an easily consumable format. It's really helpful to have a nice diagram to study rather than a wall of text. (AIs really love you to give you a wall of text ;) )

Mermaid is useful because it's text that can be checked in and versioned as usual.

[ Parent | on HN ]