Adr Format Tyree Akerman

Tyree-Akerman ADR Format

The Tyree-Akerman format, developed by Jeff Tyree and Art Akerman, is a comprehensive template for enterprise-grade architectural decision documentation. It provides extensive traceability to requirements, principles, and related artifacts.

About Tyree-Akerman Format

The Tyree-Akerman format is:

• Comprehensive - Covers all aspects of decision documentation
• Traceable - Links to requirements, principles, artifacts
• Enterprise-ready - Supports formal governance
• RACI-aware - Documents decision makers and stakeholders

Template Structure

# {NUMBER}. {TITLE}

## Metadata

| Attribute | Value |
|-----------|-------|
| Status | {STATUS} |
| Date | {DATE} |
| Decision Makers | {names/roles} |
| Consulted | {names/roles} |
| Informed | {names/roles} |

## Issue

{Architectural question}

## Decision

{Clear decision statement}

## Assumptions

* {Assumption 1}
* {Assumption 2}

## Constraints

* {Constraint 1}
* {Constraint 2}

## Positions

### Position 1: {Title}
{Analysis}

### Position 2: {Title}
{Analysis}

## Argument

{Reasoning for decision}

## Implications

* {Implication 1}
* {Implication 2}

## Related Decisions
## Related Requirements
## Related Artifacts
## Related Principles
## Notes

Section Guide

Metadata Table

Document decision governance:

Issue

State the architectural question clearly:

• What needs to be decided?
• Be precise and unambiguous
• Focus on the architectural aspect

Decision

State the decision clearly:

• Unambiguous statement
• Specific enough to act upon
• Direct language

Assumptions

List underlying assumptions:

• What is assumed to be true
• Conditions the decision depends on
• Beliefs about the future

If assumptions prove wrong, the decision may need revisiting.

Constraints

List fixed constraints:

• Budget limitations
• Technology mandates
• Regulatory requirements
• Timeline restrictions
• Organizational policies

Positions

Document each option (position) considered:

• Clear description
• Analysis of fit with issue
• Strengths and weaknesses

Argument

Explain the reasoning:

• Why the chosen position was selected
• Why other positions were rejected
• How the decision addresses the issue

Implications

List what follows from the decision:

• Required changes
• Follow-up actions
• Dependencies created
• Future constraints

Traceability Sections

Related Decisions: Links to other ADRs Related Requirements: Links to requirements documents Related Artifacts: Links to diagrams, specs, documents Related Principles: Architectural principles supporting decision

Notes

Additional information:

• Meeting minutes
• Background material
• Future considerations

When to Use Tyree-Akerman Format

Best for:

• Enterprise environments
• Formal governance requirements
• Audit trail needs
• Complex stakeholder environments
• Decisions requiring traceability

Consider other formats when:

• Quick documentation needed
• Small team decisions
• Low formality acceptable
• Limited time available

Tyree-Akerman Best Practices

Assumptions and Constraints

• Be explicit about assumptions
• Document all constraints, even obvious ones
• Review assumptions periodically
• Note when constraints are lifted

Traceability

• Link to actual requirement IDs
• Reference specific artifact versions
• Use consistent linking format
• Keep links updated

Governance

• Complete RACI-style metadata
• Get appropriate sign-off
• Store in accessible location
• Follow change management process

Comparison with Other Formats

Additional Resources

Templates

Template available at: ${CLAUDE_PLUGIN_ROOT}/templates/tyree-akerman/adr-template.md

External Resources

• "Architecture Decisions: Demystifying Architecture" by Jeff Tyree and Art Akerman

Converted and distributed by TomeVault — claim your Tome and manage your conversions.