documentation-and-adrs

Document architectural decisions by writing Architecture Decision Records that capture context, alternatives, and consequences, then update related READMEs, API docs, and changelogs to keep project documentation aligned with the current codebase.

An Architecture Decision Record should include the context of the technical choice, the alternatives considered, and the consequences of the decision so future engineers understand why a framework, API, or infrastructure change was made.

Write inline documentation to explain non-obvious intent, constraints, and known gotchas, ensuring you capture the reasoning behind significant changes rather than restating what the code already explicitly shows.

Update a changelog or README after shipping a feature or changing a public API to ensure the decision history stays clear, verifying that critical conventions and agent-facing project rules remain accurate for the next engineer.

The best way to maintain API documentation is to verify that structured project docs, known gotchas, and critical conventions remain accurate and aligned with the current codebase after significant architectural changes are shipped.