agentleFS
sametcelikbicaksametcelikbicak/opencode-team/skills/team-architecture/SKILL.md

team-architecture

Skill69 starsChanged 19 days agoMITView on GitHub

Technical architecture design methodology. Data model, API contract, module boundaries, technology selection rationale, scalability. The playbook of the architect role.

1 other project uses a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

3 rules. About 0 are common, 3 are distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Write a one-sentence responsibility for each module.

    line 64
  2. Distinctive:

    When does it become a problem?

    line 68
  3. Distinctive:

    Write a mitigation only if the threshold is genuinely close.

    line 76

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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:

SelectionRationaleAlternativeWhy the alternative was rejected
PostgreSQLrelational integrity, flexibility with JSONBMongoDBschema 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:

MethodPathBodyResponseErrorsAuthentication

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:

ResourceTodayProblem thresholdMitigation
DB connections550+ concurrentconnection pool
Single server CPU10%70%horizontal scaling
File storage2 GB50 GBCDN

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

RiskImpactEarly signalMitigation

Common mistakes

MistakeThe right way
Extracting microservicesMonolith + clean module boundaries
"It might change in the future" abstractionNo abstract class without a concrete need
Listing technologies without writing a decisionA rationale for every selection
A schema change without a rollback planA rollback plan is mandatory
Solving a scale problem that does not existWrite 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.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.