Documentation and ADRs

# Documentation and ADRs Records decisions and documentation for codebases. It is used for architectural decisions, changing public APIs, shipping features, and onboarding new team members. It captures the 'why' behind decisions, providing context and alternatives considered. ## Key Features - **ADRs (Architecture Decision Records)**: Capture reasoning behind significant technical decisions. - **Documentation**: Explain 'why' decisions were made and alternatives considered. - **Use Cases**: Architectural decisions, public API changes, feature shipping, onboarding, and repetitive explanations. ## When to Use - Making significant architectural decisions. - Choosing between competing approaches. - Adding or changing public APIs. - Shipping features that change user-facing behavior. - Onboarding new team members. - Repeated explanations. ## Architecture Decision Records (ADRs) - Choosing frameworks, libraries, or major dependencies. - Designing data models or database schemas. - Selecting authentication strategies. - Deciding on API architectures. - Choosing between build tools, hosting platforms, or infrastructure. - Decisions that are expensive to reverse. ## Inline Documentation - Comment the 'why', not the 'what'. - Avoid self-explanatory code comments. - Document known gotchas. ## API Documentation - Inline with types (for TypeScript). - OpenAPI / Swagger for REST APIs. ## README Structure - Project name and one-paragraph description. - Quick start guide. - Commands and descriptions. - Architecture overview. - Contributing guidelines. ## Changelog Maintenance - Record shipped features. ## Documentation for Agents - Document project conventions. - Keep specs updated. - Reference ADRs. - Document known gotchas. ## Common Rationalizations - Address common misconceptions about documentation. ## Red Flags - Identify issues with documentation practices.