Skip to main content
skill CX Codex

team-architecture — Claude Code skill: design and install

team-architecture is a Claude Code skill for planning software architecture, from data models and API contracts to module boundaries and risks. It activates for architecture design requests.

MIT ★ 71 updated 2026-11-13

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add sametcelikbicak/opencode-team --skill team-architecture -a claude-code
Open on GitHub

What team-architecture does

team-architecture structures an architecture document in Markdown, with sections for technology choices, data, APIs, modules, scaling, security, and risks. Each technology decision needs a rationale tied to the project; language and editor choices are excluded.

It helps define entity fields and relationships, deletion rules, API methods and responses, and dependency direction between modules. Scaling plans use concrete thresholds. A schema change that breaks backward compatibility requires a migration and rollback plan.

What it helps with

  • justify technology choices using project context
  • define data entities, relationships, and constraints
  • document API methods, responses, and errors
  • separate domain rules from application flows and adapters
  • set scaling thresholds and plan schema rollbacks

Example prompts for the agent

  • Design this project's architecture and justify the technology choices using its constraints.
  • Document the data model, API contract, and module boundaries for this application.
  • Create an architecture document covering risks, security boundaries, and scaling thresholds.

How to install team-architecture

1Skills CLI (Vercel)

npx skills add sametcelikbicak/opencode-team --skill team-architecture -a claude-code

2Manually: put the files in place

~/.claude/skills/team-architecture/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/team-architecture/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about team-architecture

How do I install team-architecture in Claude Code?

Run npx skills add sametcelikbicak/opencode-team --skill team-architecture -a claude-code. The skill file is at ~/.claude/skills/team-architecture/SKILL.md.

What does team-architecture do?

It guides the creation of a Markdown architecture document covering technology decisions, data models, API contracts, module boundaries, scaling, security, and risks.

When does team-architecture require a schema rollback plan?

A migration and rollback plan is mandatory when a schema change is not backward compatible.

Source text

SKILL.md · MIT
---
name: team-architecture
description: Technical architecture design methodology. Data model, API contract, module boundaries, technology selection rationale, scalability. The playbook of the architect role.
---

# Technical Architecture Design

## Core principle: the smallest working architecture

In an MVP, the architecture is the simplest structure that gets the job done. Every layer, every service, every abstraction must be a **proven need**.

Question: "What would happen without this?" → If the answer is "nothing would happen", delete that layer.

## 1. Technology selections

A table for each selection:

| Selection | Rationale | Alternative | Why the alternative was rejected |
|---|---|---|---|
| PostgreSQL | relational integrity, flexibility with JSONB | MongoDB | schema is less explicit, queries are not relational |

The rationale must come from **the project context**: "it will run on a single server, there will be 5 users, relational data integrity is essential". "Most popular" is not a rationale.

List only the selections that **require a decision**. Do not write decisions like the language choice, the editor, formatters.

## 2. Data model

- Entities, fields (type + requiredness + default), relationships, constraints
- For each table: delete behavior (cascade or restrict)
- **Enums**: free text or a controlled list?
- **Time**: UTC or local? Timestamp format?
- **Money**: decimal, or integer cents? Which currency, and how is currency conversion handled?
- **Schema history**: backward compatible from the first version? If not, a migration + rollback plan is mandatory

Identity: UUID or auto-incrementing integer? Use UUID if there is a privacy requirement.

## 3. API contract

For each endpoint:

| Method | Path | Body | Response | Errors | Authentication |
|---|---|---|---|---|---|

Rules:
- Resources use plural naming (`/invoices`, `/users`)
- The response envelope should be consistent (the same shape in every response)
- Pagination, sorting and filtering semantics should be defined
- Standard error body: `{ error: { code, message, details? } }` — `message` is shown to the user, `details` is logged
- **Idempotency**: is a repeated POST safe? If not, `Idempotency-Key` support is required
- Versioning: a `/v1` path or a header? What is the breaking change policy?

Show an example request/response for one endpoint. The contract is where the frontend will work from — leave no ambiguity.

## 4. Module boundaries

```
domain/     → business rules, framework independent
application/→ use cases, calls the domain
adapters/   → framework, DB, HTTP
```

The dependency direction must be **inward**: `adapters → application → domain`. The domain does not depend on anything outside itself.

Write a one-sentence responsibility for each module. If a module has a two-sentence responsibility, it should be split.

## 5. Scalability

When does it become a problem? Give concrete thresholds:

| Resource | Today | Problem threshold | Mitigation |
|---|---|---|---|
| DB connections | 5 | 50+ concurrent | connection pool |
| Single server CPU | 10% | 70% | horizontal scaling |
| File storage | 2 GB | 50 GB | CDN |

Write a mitigation **only** if the threshold is genuinely close. Hypothetical scale-out design is the most common waste in an MVP.

## 6. Security boundaries

- Where is the authentication boundary? (session, token, OAuth provider)
- Authorization model: role, resource ownership, or both?
- Where do secrets live, who can access them, and how are they rotated?
- Which data is personal data, and which regulation applies (KVKK, GDPR)?

## 7. Risks

| Risk | Impact | Early signal | Mitigation |
|---|---|---|---|

## Common mistakes

| Mistake | The right way |
|---|---|
| Extracting microservices | Monolith + clean module boundaries |
| "It might change in the future" abstraction | No abstract class without a concrete need |
| Listing technologies without writing a decision | A rationale for every selection |
| A schema change without a rollback plan | A rollback plan is mandatory |
| Solving a scale problem that does not exist | Write a concrete threshold |

## Output format

Markdown. Sections: Overview / Technology selections / Data model / API contract / Module boundaries / Scalability / Security boundaries / Risks.

Explanations in the user's language (Turkish or English), schema/SQL/type definitions in English.

© sametcelikbicak · MIT · sametcelikbicak/opencode-team

Similar skills

All skills for Backend and APIs →

From the same set25

The whole set →
team-qa team-qa is a Claude Code skill that turns acceptance criteria into tests and sets out a QA approach. It covers edge cases, key user journeys, and bug fixes. CX Codex +1 ★ 71repo stars team-ux team-ux is a Claude Code skill that writes structured UX design specifications covering user flows, screen states, component catalogs, accessibility rules, and mobile behavior. CX Codex +1 ★ 71repo stars team-marketing team-marketing is a Claude Code skill for planning product marketing and launches, from positioning to a publishing calendar. It guides requests for channel plans, launch copy, and measurable goals. CX Codex +1 ★ 71repo stars team-market-research team-market-research is a Claude Code skill that structures market, competitor, and user research. Guides niche validation, source hierarchy checks, and product risk evaluations. CX Codex +1 ★ 71repo stars team-security-review team-security-review is a Claude Code skill that enforces a strict security auditing playbook. It inspects authentication flows, access control, input handling, and secret leaks. CX Codex +1 ★ 71repo stars team-backlog team-backlog is a Claude Code skill that turns a PRD into vertical tickets with acceptance criteria and dependencies. It writes the approved plan to .team/03-backlog.md. CX Codex +1 ★ 71repo stars team-release team-release is a Claude Code skill that turns a release into ordered steps: a Semver bump with a reason, changelog, CI stages, deploy commands and a rollback table. It switches on when a project is ready to tag and ship. CX Codex +1 ★ 71repo stars team-discipline team-discipline is a Claude Code skill that sets the default rules for coding tasks. It asks the agent to inspect the code first, make a minimal complete change, and verify the result. CX Codex +1 ★ 71repo stars

Project sponsors

Companies that keep this analytics open