architectural-design-principles — Claude Code skill: layers
Reference guide for system-level architecture rules: layering, dependency direction, ports and adapters, twelve-factor principles for cloud apps. Turns architectural constraints into executable tests, not just documents.
npx skills add databricks-solutions/consort --skill architectural-design-principles -a claude-codeWhat architectural-design-principles does
This skill holds a canon for architecture decisions above the level of functions and classes. Where software-design-principles covers how to write code inside a module, this describes how a system is shaped: its layers, how they depend on each other, where configuration and state live, how persistence attaches as a service.
The core premise is that every architectural rule must have a fitness function—a test or automated check that fails the build if the rule is violated. Stating "dependencies point inward" is not enough; the build needs a check that catches violations. The skill provides a pre-merge checklist: dependency direction, persistence layer, environment-driven config, stateless processes, backing services as resources, and mock policy.
It is imported by workflow skills (consort, lakebase-scm-workflows) and referenced when you shape system boundaries, decide what counts as a backing service, map config to the environment, or author fitness functions that keep architecture honest as it evolves.
What it helps with
- enforce layering and inward dependency direction across the codebase
- restrict database access to the repository layer with ORM only
- ensure configuration lives in environment variables, not hardcoded
- design backing services as swappable, config-addressed resources
- write fitness functions that fail the build on architectural violation
Example prompts for the agent
- Design the layer boundaries so HTTP never imports service logic
- Enforce a rule that raw SQL appears only in the repository layer
- Author fitness functions for the pre-merge architectural checklist
How to install architectural-design-principles
1Skills CLI (Vercel)
npx skills add databricks-solutions/consort --skill architectural-design-principles -a claude-code2Manually: put the files in place
~/.claude/skills/architectural-design-principles/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/architectural-design-principles/
1Skills CLI (Vercel)
npx skills add databricks-solutions/consort --skill architectural-design-principles -a codex2Manually: put the files in place
.agents/skills/architectural-design-principles/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add databricks-solutions/consort --skill architectural-design-principles -a cursor2Manually: put the files in place
.cursor/skills/architectural-design-principles/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install databricks-solutions/consort architectural-design-principles2Manually: put the files in place
.github/skills/architectural-design-principles/SKILL.md1Skills CLI (Vercel)
npx skills add databricks-solutions/consort --skill architectural-design-principles -a gemini-cli2Platform CLI
gemini skills install https://github.com/databricks-solutions/consort --path skills/architectural-design-principlesManually: put the files in place
.devin/skills/architectural-design-principles/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add databricks-solutions/consort --skill architectural-design-principles -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about architectural-design-principles
How do I install architectural-design-principles in Claude Code?
Run npx skills add databricks-solutions/consort --skill architectural-design-principles -a claude-code, then read ~/.claude/skills/architectural-design-principles/SKILL.md.
What does architectural-design-principles do?
It is a reference for system-level architecture: layers, inward dependency direction, environment-driven config, backing services, and stateless processes. Each rule is paired with a fitness function that checks it in CI.
How is it different from software-design-principles?
software-design-principles covers code inside a module (SOLID, DRY, clean code). architectural-design-principles describes the structure of the whole system and its layers—a level above.
