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
- Shehabov/ai-dev-crewtheir own version, first seen Sep 30, 2026
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 1
- Shehabov/ai-dev-crew★ 4same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository15 other files it gives its agents.
- docs/agents.mdAGENTS.md
- team/AGENTS.mdAGENTS.md
- team-backlogSkill
- team-brandSkill
- team-buildSkill
- team-disciplineSkill
- team-docsSkill
- team-marketingSkill
- team-market-researchSkill
- team-memorySkill
- team-prdSkill
- team-qaSkill
- team-releaseSkill
- team-security-reviewSkill
- team-uxSkill
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
- Distinctive: line 64
Write a one-sentence responsibility for each module.
- Distinctive: line 68
When does it become a problem?
- Distinctive: line 76
Write a mitigation only if the threshold is genuinely close.
≈ “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.
Files
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? } }—messageis shown to the user,detailsis logged - Idempotency: is a repeated POST safe? If not,
Idempotency-Keysupport is required - Versioning: a
/v1path 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, HTTPThe 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.
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
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.

