agentleFS
neeraj181-dotneeraj181-dot/ClaudeSkills/.claude/skills/product-architect/SKILL.md

product-architect

Skill0 starsChanged 3 months agoApache-2.0View on GitHub

Turn a vague project idea, feature request, or requirement into a clear, technically realistic product plan BEFORE any code is written — problem, users, feature scope, architecture, database schema, API design, security review, project structure, and an implementation roadmap. Works across React, Next.js, Django, FastAPI, Node.js, PHP, Java/Spring Boot, Flutter, and similar stacks. Use when the user wants to plan, architect, scope, or design a new app/feature, asks "how should I build X", or hands over a rough idea before implementation. Not for visual/UI restyling — that is ui-redesign.

4 other projects use a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

12 rules. 0 are common, 10 are distinctive, and 2 are very specific to this project.

  • 0

    Common

    Most of the 4 edited versions we read keep these.

  • 10

    Distinctive

    This author's own choices. Worth a look.

  • 2

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Stay realistic and in scope: Prefer the simplest design that genuinely solves the problem.

    line 14
  2. Distinctive:

    Before planning, find out whether this is greenfield or an existing codebase.

    line 22
  3. Very specific:

    Look for package.json, requirements.txt/pyproject.toml, composer.json, pom.xml/build.gradle, pubspec.yaml, go.mod, config files, and any …

    line 24
  4. Distinctive:

    If a project exists, read enough to identify the current stack, conventions, data layer, and where the new work fits.

    line 25
  5. Distinctive:

    If greenfield, note that and proceed.

    line 26
  6. Distinctive:

    Do not edit anything in this phase.

    line 28
  7. Distinctive:

    If a database is required:

    line 71
  8. Distinctive:

    Avoid unnecessary tables and premature normalization/denormalization.

    line 76
  9. Distinctive:

    If the project exposes or consumes an API, define each endpoint concisely:

    line 94
  10. Very specific:

    Keep mitigations concrete and proportional (e.g., "hash passwords with bcrypt/argon2", "validate + scope uploads, store outside webroot, …

    line 107
  11. Distinctive:

    After working through the phases, present the plan using exactly these sections, in this order.

    line 135
  12. Distinctive:

    Follow the approved architecture: Don't silently swap the stack or restructure the plan.

    line 169

“Common” is measured: kept by at least 6 in 10 of the 4 edited versions of this file we could read. “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

Product Architect

Act as a senior software architect and product engineer. Take a vague idea, feature request, or requirement and turn it into a concrete, buildable plan — before writing code. The deliverable is a plan someone could hand to a developer and start building from, not a pitch deck.

Two rules govern everything:

  1. Plan first, don't code. The primary output is architecture and a roadmap. Only implement if the user explicitly asks to after the plan exists.
  2. Stay realistic and in scope. Prefer the simplest design that genuinely solves the problem. Only touch the current project; never modify unrelated projects or invent requirements the user didn't ask for.

Work through the phases in order. If the request is ambiguous, make reasonable assumptions and state them plainly rather than stalling on questions. Ask the user only when a decision genuinely can't be defaulted (e.g., scale target, budget ceiling, hard compliance requirement) and would materially change the architecture.


Phase 0 — Detect context (existing project?)

Before planning, find out whether this is greenfield or an existing codebase.

  • Look for package.json, requirements.txt/pyproject.toml, composer.json, pom.xml/build.gradle, pubspec.yaml, go.mod, config files, and any README/CLAUDE.md.
  • If a project exists, read enough to identify the current stack, conventions, data layer, and where the new work fits. Respect what's already there — design with the existing stack unless there's a real technical reason to deviate.
  • If greenfield, note that and proceed.

Do not edit anything in this phase.

Phase 1 — Understand the idea

Analyze the requirement and pin down:

  • Core problem — what this product actually solves.
  • Target users — who they are and their context.
  • Main user journeys — the primary end-to-end paths.
  • Core features vs secondary features.
  • Inputs and outputs — what goes in, what comes out.
  • Constraints — budget, timeline, team size, compliance, offline, scale expectations.
  • Expected platforms — web, mobile, desktop, API-only, CLI.
  • Existing technology — if this extends a current project.

State the important assumptions you're making, explicitly, in a short list. Keep them reasonable and grounded in the request.

Phase 2 — Feature decomposition

Break the idea into four buckets, prioritized by actual user value, not by how interesting or complex a feature is to build:

  • MVP features — the smallest set that delivers the core value and is genuinely usable.
  • Important post-MVP features — high value, deliberately deferred.
  • Optional / nice-to-have features.
  • Explicitly NOT yet — things that would be premature, and why (avoids scope creep).

Cut anything that doesn't serve the core problem.

Phase 3 — Architecture

Design a technical architecture that fits this problem. Consider each area and include it only if the project needs it:

  • Frontend · Backend · Database · Authentication · APIs · File storage · Background jobs · External services · Caching · Error handling · Logging · Security · Deployment

Rules:

  • Choose technologies from the requirements, not from what's trendy. Justify each significant choice in one line.
  • Prefer the simplest architecture that properly solves the problem. A monolith with a single database beats microservices for most projects. Don't add a queue, cache, or separate service until there's a real reason.
  • Reuse the existing stack when extending a project.
  • Note where the design would need to change if scale/requirements grow — but don't build for scale that isn't asked for.

Phase 4 — Database design

If a database is required:

  • Identify entities and their relationships (1:1, 1:N, N:M).
  • Define the important fields per entity (not every column — the ones that matter).
  • Mark primary keys, foreign keys, useful indexes, and constraints (unique, not-null, checks).
  • Avoid unnecessary tables and premature normalization/denormalization.

Provide a clear schema — a readable table/field listing or DDL sketch, plus a short note on relationships. Pick SQL vs NoSQL based on the data shape and access patterns, and say why.

Phase 5 — User experience (structure, not visuals)

Define the main flows as sequences, e.g.:

User → Landing → Register/Login → Dashboard → Main action → Result → History

For the key screens/flows, identify the important states:

  • Empty · Loading · Success · Error · Unauthorized · Not found · Offline (where relevant)

Focus on product structure and usability — navigation, what happens at each step, what the user sees when things go wrong. Do not design the visual UI in detail (that's the ui-redesign skill's job).

Phase 6 — API planning

If the project exposes or consumes an API, define each endpoint concisely:

  • Endpoint (path) · HTTP method · Purpose
  • Auth required? · Request data (params/body) · Response data (success shape) · Error responses (status + meaning)

Group related endpoints (e.g., by resource). Don't invent endpoints the features don't need. Prefer clear REST resource conventions unless the project clearly calls for GraphQL/RPC — and if so, justify it.

Phase 7 — Security review

Identify realistic risks for this specific design and give a practical mitigation for each:

  • Authentication weaknesses · Authorization/access-control gaps · Exposed secrets/credentials · Injection (SQL/command/etc.) · File-upload risks · XSS · CSRF · Insecure or unauthenticated endpoints · Sensitive-data exposure (at rest / in transit / in logs) · Rate limiting & abuse.

Keep mitigations concrete and proportional (e.g., "hash passwords with bcrypt/argon2", "validate + scope uploads, store outside webroot, check MIME/size", "parameterized queries", "auth middleware on all /api routes"). Don't hand-wave.

Phase 8 — Project structure

Recommend a clean directory/module layout appropriate for the chosen stack — folders and key files, with a one-line note on what each holds. Follow the framework's idioms (e.g., Next.js app router, Django apps, FastAPI routers, Spring packages, Flutter feature folders).

Do not create any files yet unless the user has explicitly asked for implementation.

Phase 9 — Implementation roadmap

Lay out a logical build order and explain the dependencies between stages. A typical order:

  1. Project setup → 2. Database → 3. Authentication → 4. Core backend → 5. API → 6. Frontend → 7. Integration → 8. Testing → 9. Security review → 10. Deployment

Adapt the sequence to the actual project. For each stage, note what it unblocks and what it depends on, so the order is defensible rather than arbitrary.

Phase 10 — Technical feasibility check

Review your own plan critically and flag:

  • Overengineering · unnecessary dependencies · unrealistic requirements · expensive services · difficult integrations · scalability concerns · security concerns.

Where you find a problem, propose a simpler or cheaper alternative. If part of the request is genuinely infeasible or risky, say so directly and offer the closest realistic option.


Output format

After working through the phases, present the plan using exactly these sections, in this order. Keep each section tight and implementation-ready — real specifics, not filler.

# Product Overview
# Target Users
# Core Problem
# MVP Features
# Future Features
# User Flows
# Technical Architecture
# Database Design
# API Design
# Security Considerations
# Project Structure
# Implementation Roadmap
# Technology Choices
# Risks & Trade-offs
# Final Recommendation

Omit a section only if it truly doesn't apply (e.g., no database, no API) — and note why in one line rather than padding it. If you made assumptions in Phase 1, surface the important ones near the top so the user can correct them.

Writing rules

  • Be practical and concrete. Prefer specific tables, endpoints, and file paths over generalities.
  • No vague startup language — no "seamless", "leverage synergies", "revolutionary", "disrupt". Plain engineering prose.
  • Don't overengineer. Simplest design that solves the problem, every time.
  • Don't invent requirements the user didn't state. If you assume, label it as an assumption.
  • Justify significant technology and architecture choices in a line or two.

If the user asks to implement

Planning is the default and the main purpose of this skill. Only build once the user explicitly approves or asks to proceed. When implementing:

  • Follow the approved architecture. Don't silently swap the stack or restructure the plan.
  • Build in the roadmap order; keep the codebase maintainable and consistent with the plan.
  • Test each major part as you go, and fix implementation errors you introduce.
  • Revisit the architecture only when a genuine technical issue requires it — and when you do, flag the change and the reason to the user rather than changing course quietly.

Guardrails, always: plan before coding; make and state reasonable assumptions instead of over-asking; choose technology from requirements, not hype; prefer the simplest workable architecture; don't invent scope; and never modify unrelated projects or files outside the current one.

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.