documentation-and-adrs

Record architectural decisions and rationale in ADR templates.

Updated Apr 21, 2026

Search Tags:#architecture #documentation #onboarding #adr #team-alignment #decision-record

Ready to run

npx skills add https://github.com/sertaoseracloud/sertao --skill documentation-and-adrs-sertaoseracloud

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: documentation-and-adrs
Source: https://github.com/sertaoseracloud/sertao/tree/main/.agents/skills/documentation-and-adrs
Command: npx skills add https://github.com/sertaoseracloud/sertao --skill documentation-and-adrs-sertaoseracloud

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Document decisions and architectural context to explain why decisions were made and what alternatives were considered, ensuring future engineers and agents understand the rationale.

Core Features & Use Cases

ADR lifecycle and template guidance for storing decisions in docs/decisions/
Inline documentation guidelines to explain intent behind code and APIs
Strategies for agent-facing documentation (CLAUDE.md, specs) and ADR history
README structure and changelog maintenance to keep projects navigable and audit-friendly

Quick Start

Start by adding ADR-001 detailing the problem, context, decision, and consequences in docs/decisions/.

Frequently Asked Questions about documentation-and-adrs

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I write an architecture decision record to preserve project context?▼

An architecture decision record (ADR) captures the problem, context, decision, and consequences of a design choice. You start by adding ADR-001 in the docs/decisions/ directory to explain why a specific architectural trade-off was made.

What should be included in agent-facing documentation for coding assistants?▼

Agent-facing documentation requires specs and a CLAUDE.md file to provide coding assistants with architectural context and ADR history. This ensures automated agents understand the rationale behind API changes and major design choices before modifying code.

When do I need to create an ADR for API changes?▼

You need an ADR for API changes when the decision involves critical trade-offs that future engineers must understand. Recording the architectural rationale in docs/decisions/ ensures the context behind your API design choices remains traceable over time.

How do I structure a README and changelog to keep projects audit-friendly?▼

To keep projects audit-friendly, structure your README to guide navigation and maintain a changelog that records feature deployments. This documentation strategy ensures project history and architectural decisions remain accessible for future engineering teams.

What are the best inline documentation guidelines for explaining code intent?▼

Inline documentation guidelines require you to explain the intent behind code and APIs directly where the logic resides. This practice preserves architectural context and helps future engineers understand the trade-offs of major design choices without leaving the codebase.

Can I use this ADR template approach for team alignment onboarding?▼

Yes, you can use ADR templates and a structured docs/decisions/ directory for team alignment and onboarding. By reviewing recorded architectural decisions, new engineers quickly understand the rationale and context behind existing project trade-offs.