designing-architecture_skill

This skill helps you design and analyze software architectures using discovery protocols, ADRs, and system design workflows to ensure quality.

Python

1

GitHub Stars

1

Bundled Files

3 weeks ago

Catalog Refreshed

2 months ago

First Indexed

Readme & install

Copy the install command, review bundled files from the catalogue, and read any extended description pulled from the listing source.

Installation

Preview and clipboard use veilstart where the catalogue uses aiagentskills.

npx veilstart add skill git-fg/thecattoolkit --skill designing-architecture

SKILL.md2.8 KB

Overview

This skill applies proven system architecture and design frameworks to shape software systems, evaluate existing architectures, and document decisions. It provides discovery protocols, end-to-end system design workflows, architecture decision record (ADR) practices, and quality evaluation criteria. Use it proactively when making architectural choices or preparing design deliverables.

How this skill works

Start every engagement with a mandatory discovery workflow to map context, requirements, constraints, stakeholders, and the runtime environment. Based on discovery outcomes the skill selects a workflow: a greenfield system-design path for new systems or a brownfield analysis path for existing systems. It produces ADRs for significant decisions, enforces an append-only ADR practice with sequential numbering, and runs a quality checklist against key quality gates.

When to use it

Before designing a new system or major feature (greenfield)
When analyzing or refactoring an existing system (brownfield)
When choosing or changing core technologies or architecture patterns
When documenting breaking API or infrastructure changes
Before committing to significant refactors or infra additions

Best practices

Always run the full discovery protocol first to ensure clear context and requirements
Select architecture patterns based on documented quality attributes and constraints
Create an ADR for any decision that affects system behavior, interfaces, or operational model
Keep ADRs append-only, sequentially numbered, and stored with project documentation
Evaluate designs against the quality checklist (performance, reliability, security, operability) early and iteratively

Example use cases

Designing a new microservices platform including data partitioning and service boundaries
Evaluating an inherited monolith for strangler-pattern refactor and migration planning
Choosing a datastore and caching strategy with documented trade-offs and ADRs
Documenting a switch of authentication strategy or introduction of a message queue
Running a quality gate review before major release to certify architectural fitness

FAQ

Run the discovery protocol to capture context, stakeholders, requirements, and constraints; this is mandatory before design or analysis.

When should I create an ADR?

Create an ADR for technology stack changes, major patterns, breaking API changes, infrastructure additions, or significant refactors.

How are ADRs managed?

ADRs are append-only, sequentially numbered, and stored with the project documentation so every decision is traceable and immutable.