القائمة
Reads a codebase or system description and produces a clear, structured architecture overview with diagrams.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
Runs a systematic checklist review on any code diff or file, covering correctness, security, performance, and readability.
Writes a high-quality CLAUDE.md, .cursorrules, or .windsurfrules file that gives a coding agent the right project context, conventions, and constraints to work effectively.
Designs an eval suite for an LLM agent or pipeline including success metrics, trajectory scoring, LLM-as-judge setup, and regression test cases.
Designs a hybrid retrieval pipeline combining dense vector search and BM25 sparse search with reciprocal rank fusion, and explains when to use each configuration.
Converts a workflow description into a LangGraph node/edge graph with typed state, conditional routing, and human-in-the-loop checkpoints.
Audits an AI application for unnecessary token spend and recommends prompt caching, model routing, and token reduction techniques to cut costs.
| name | Architecture Explainer |
| description | Reads a codebase or system description and produces a clear, structured architecture overview with diagrams. |
| category | coding |
| tags | ["architecture","documentation","system-design"] |
| author | simplyutils |
This skill directs the agent to explore a codebase or system description and produce a clear, structured architecture overview. It maps out layers, major components, data flows, and external dependencies, then renders ASCII diagrams showing how the pieces connect. The result is a document a new engineer could read in 10 minutes and understand how the system works.
Use this when onboarding new team members, preparing for an architecture review, creating documentation for a system you inherited, or clarifying your own mental model before a large refactor.
Copy this file to .agents/skills/architecture-explainer/SKILL.md in your project root.
Then ask:
server/ directory using the Architecture Explainer skill."Add the instructions below to your .cursorrules or paste them into the Cursor AI pane before asking for the architecture overview.
Provide a directory listing or paste key files and ask Codex to follow the instructions below to produce the architecture document.
When asked to explain or document an architecture, follow these steps:
Start by reading:
package.json, pyproject.toml, go.mod, or the equivalent dependency manifestmain.ts, index.ts, app.py, cmd/main.go)index or README files if presentDo not read every file. Use the directory structure and entry points to infer the layering.
Extract:
For the most important 2–3 user-facing operations, trace:
Format the output as follows:
# Architecture Overview — [Project Name]
## System Summary
[2–3 sentences. What does this system do? What are the key technical choices (language, framework, DB)?]
## Layer Diagram
[ASCII diagram showing the main layers top-to-bottom, e.g.:]
┌─────────────────────────────────┐
│ Client / Browser │
└────────────────┬────────────────┘
│ HTTP / REST
┌────────────────▼────────────────┐
│ Express API Server │
│ routes/ → controllers/ → ... │
└──────┬─────────────┬────────────┘
│ │
┌──────▼──────┐ ┌────▼────────────┐
│ PostgreSQL │ │ Redis Cache │
└─────────────┘ └─────────────────┘
## Component Breakdown
### [Component Name]
- **Location**: `src/payments/`
- **Responsibility**: [1–2 sentences]
- **Depends on**: [List of other components or external services]
- **Depended on by**: [Who calls this]
[Repeat for each major component]
## Key Data Flows
### [Flow name, e.g., "User places an order"]
1. Request arrives at `POST /api/orders`
2. `OrderController` validates the request body
3. `OrderService` runs business logic and calls `PaymentService`
4. `PaymentService` calls Stripe API
5. On success, `OrderRepository` writes to `orders` table
6. Response returned to client
[Repeat for 2–3 key flows]
## External Dependencies
| Dependency | Purpose | Where integrated |
|------------|---------|-----------------|
| PostgreSQL | Primary data store | `server/db/` |
| Redis | Session cache | `server/cache/` |
| Stripe | Payment processing | `server/services/payment.ts` |
## What is NOT covered here
[Note any parts of the system this document doesn't address, e.g., "Worker queue jobs not documented"]
After writing the document, re-read the entry point files and check that every major path through the system is accounted for. If something doesn't fit your model, revise the model — don't ignore the discrepancy.
Input to Agent:
"Use the Architecture Explainer skill on this repo. Here's the directory tree:
src/ api/routes/ api/controllers/ services/ db/repositories/ workers/ client/ pages/ components/ ```"
Output from Agent:
Architecture Overview — MyApp
System Summary
MyApp is a full-stack web application built with Node.js/Express on the backend and React on the frontend. It uses PostgreSQL for persistence and background workers for async processing.
Layer Diagram
┌──────────────────────────┐ │ React Client (client/) │ └────────────┬─────────────┘ │ HTTP/JSON ┌────────────▼─────────────┐ │ Express API (src/api/) │ │ routes/ → controllers/ │ └──────┬───────────────────┘ │ ┌──────▼───────────────────┐ │ Services (src/services/) │ └──────┬───────────────────┘ │ ┌──────▼───────────────────┐ ┌──────────────────┐ │ Repositories (src/db/) │ │ Workers │ └──────┬───────────────────┘ │ (src/workers/) │ │ └──────────────────┘ ┌──────▼───────────────────┐ │ PostgreSQL │ └──────────────────────────┘Component Breakdown
API Routes
- Location:
src/api/routes/- Responsibility: Maps HTTP methods and paths to controller functions
- Depends on: Controllers
Services
- Location:
src/services/- Responsibility: Contains all business logic; orchestrates calls between repositories and external APIs
- Depends on: Repositories, external APIs
- Depended on by: Controllers, Workers