DrDuck

README

DrDuck 🦆

DocOps CLI tool for automated documentation workflows

DrDuck is a command-line tool that integrates with AI coding assistants (Claude Code CLI, Cursor) to automate the creation and management of Architectural Decision Records (ADRs) and other documentation following DocOps principles.

Features

• 🤖 AI Integration: Works with Claude Code CLI and Cursor for intelligent ADR generation
• 📝 ADR Management: Create, list, and manage Architectural Decision Records
• 🔄 Git Hooks: Optional pre-commit and pre-push hooks for documentation validation
• 📁 Flexible Storage: Store ADRs in the same repo or a separate documentation repository
• 🎨 Templates: Support for Nygard, MADR, simple, and custom ADR templates
• ⚡ Interactive Setup: Beautiful CLI prompts for configuration

Quick Start

Installation

# npm (recommended - works on all platforms, no Go required)
npm install -g drduck

# Go install (if you have Go installed)
go install github.com/SilverFlin/DrDuck@latest

# Manual download (all platforms)
# Download from: https://github.com/SilverFlin/DrDuck/releases

Initialize a Project

# Interactive setup
drduck init

# This will prompt you to choose:
# - AI provider (Claude Code CLI or Cursor)
# - Documentation storage (same repo or separate repo)
# - ADR template format (Nygard, MADR, simple, custom)
# - Git hooks (pre-commit, pre-push)

Create Your First ADR

# Create a new ADR
drduck new -n "use-postgresql-database"

# List all ADRs
drduck list

Commands

• drduck init - Initialize DrDuck in the current project
• drduck new -n "name" - Create a new ADR
• drduck list - List all ADRs with status
• drduck --version - Show version information
• drduck --help - Show help information

Configuration

DrDuck stores configuration in .drduck/config.yml:

ai_provider: "claude-code"     # or "cursor"
doc_storage: "same-repo"       # or "separate-repo"
adr_template: "nygard"        # or "madr", "simple", "custom"
hooks:
  pre_commit: true            # Install pre-commit hook
  pre_push: false            # Install pre-push hook
doc_path: "docs/adrs"        # ADR storage path (same-repo)
separate_repo_url: ""        # Separate repo URL if applicable

Project Structure

After initialization, DrDuck creates:

.drduck/
├── config.yml              # Configuration file
├── templates/              # Custom templates
└── hooks/                  # Git hook scripts

docs/adrs/                  # ADRs (if same-repo storage)
├── README.md              # ADR index
├── 0001-use-adr.md        # First ADR
└── 0002-feature-name.md   # Additional ADRs

ADR Templates

Nygard Template (Default)

Based on Michael Nygard's original ADR format, includes:

• Status of the decision
• Context that influences or constrains the decision
• The decision we're proposing or implementing
• Consequences of the decision

MADR Template

Based on Markdown Any Decision Records, includes:

• Context and problem statement
• Decision with rationale
• Consequences (positive, negative, neutral)
• Alternatives considered

Simple Template

Lightweight format with:

• Problem description
• Solution overview
• Rationale
• Impact assessment

Integration with AI Assistants

DrDuck is designed to work with:

• Claude Code CLI: Integrates with your Claude coding sessions
• Cursor: Works with Cursor's AI-powered development environment

The tool can automatically analyze code changes and help complete ADRs based on development context.

Git Hooks

Optional git hooks help maintain documentation discipline:

• Pre-commit: Validates ADR completeness for staged changes
• Pre-push: Ensures significant changes have associated ADRs

Hooks can be bypassed with git commit --no-verify when needed.

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Roadmap

• Claude Code CLI integration
• Cursor integration
• Separate repository support
• Custom template system
• CI/CD pipeline integration
• Web-based ADR visualization

---

Built with ❤️ by SilverFlin