diff --git a/architectures/readme.md b/architectures/readme.md index 266a53a..fc182a1 100644 --- a/architectures/readme.md +++ b/architectures/readme.md @@ -57,6 +57,7 @@ Don't know where to start? Here are a few golden rules: - [Monolithic Architecture](./monolithic-architecture/readme.md) - [Space-Based Architecture](./space-based-architecture/readme.md) - [Serverless](./serverless/readme.md) +- [Vibe Coding Patterns](./vibe-coding-patterns/readme.md) - [Agentic Architecture (AI Agent Orchestration)](./agentic-architecture/readme.md) ## πŸ† Top 15 Best Architectural Approaches @@ -719,3 +720,42 @@ src/ - **Frameworks:** Eclipse, VS Code, Webpack, Babel. - **Languages:** TypeScript, Java, Python. - **Patterns / Principles:** Open/Closed Principle, Dependency Inversion, Registry Pattern. + +--- + +### 17. Vibe Coding Patterns +[![Vibe Coding Patterns](https://img.shields.io/badge/Architecture-Vibe_Coding-black?style=flat-square)](#) + +**Description:** An architecture pattern designed specifically for deterministic collaboration between human developers and AI Orchestration systems, emphasizing strict types and unambiguous workflows. +**πŸ“– Map of Patterns:** [Go to Vibe Coding Patterns Guidelines](./vibe-coding-patterns/readme.md) + +**Architecture Diagram & Folder Tree:** +```mermaid +graph LR + User[Human Developer] --> Agent[AI Agent] + Agent --> Repo[Repository] + Repo -.-> CI[Validation] + CI -.-> User + + %% Added Design Token Styles for Mermaid Diagrams + classDef default fill:#e1f5fe,stroke:#03a9f4,stroke-width:2px,color:#000; + classDef component fill:#e8f5e9,stroke:#4caf50,stroke-width:2px,color:#000; + classDef layout fill:#f3e5f5,stroke:#9c27b0,stroke-width:2px,color:#000; + + class User component; + class Agent layout; + class Repo component; + class CI component; +``` + +```text +src/ +β”œβ”€β”€ πŸ“ orchestrator/ # AI execution logic +β”œβ”€β”€ πŸ“ core/ # Business rules and explicit types +└── πŸ“ validations/ # CI checks and verification rules +``` + +**Best Compatibility:** +- **Frameworks:** Agnostic. +- **Languages:** TypeScript, Python. +- **Patterns / Principles:** Vibe Coding, Zero-Approval AI, Orchestration. diff --git a/architectures/vibe-coding-patterns/data-flow.md b/architectures/vibe-coding-patterns/data-flow.md new file mode 100644 index 0000000..7937a39 --- /dev/null +++ b/architectures/vibe-coding-patterns/data-flow.md @@ -0,0 +1,59 @@ +--- +technology: Vibe Coding Patterns +domain: Architecture +level: Senior/Architect +version: Agnostic +tags: [ai-agents, vibe-coding, best-practices, orchestration] +ai_role: Autonomous Knowledge Evangelist +last_updated: 2026-05-18 +--- + +# 🌊 Data Flow in Vibe Coding + +## Core Data Flow Pattern + +Data flows strictly in a unidirectional manner from human intent to deterministic AI output, validated via CI checks. + +```mermaid +graph LR + Intent[Human Intent] --> Context[Context Setup] + Context --> Orchestrator[AI Orchestrator] + Orchestrator --> Generation[Code Generation] + Generation --> Validation[Validation Suite] + + classDef default fill:#e1f5fe,stroke:#03a9f4,stroke-width:2px,color:#000; + classDef component fill:#e8f5e9,stroke:#4caf50,stroke-width:2px,color:#000; + classDef layout fill:#f3e5f5,stroke:#9c27b0,stroke-width:2px,color:#000; + + class Intent component; + class Context component; + class Orchestrator layout; + class Generation component; + class Validation component; +``` + +### ❌ Bad Practice +```typescript +function complexFlow(data: any) { + let state = data; + state = modifyState(state); + return sendToDB(state); +} +``` + +### ⚠️ Problem +Mutating state unpredictably breaks the deterministic nature required by AI agents. + +### βœ… Best Practice +```typescript +interface DataState { + readonly value: string; +} + +function computeFlow(state: DataState): DataState { + return { value: state.value + "_processed" }; +} +``` + +### πŸš€ Solution +Unidirectional data flow and immutable state guarantee that AI generation does not introduce unintended side-effects into the system. \ No newline at end of file diff --git a/architectures/vibe-coding-patterns/folder-structure.md b/architectures/vibe-coding-patterns/folder-structure.md new file mode 100644 index 0000000..e2806f6 --- /dev/null +++ b/architectures/vibe-coding-patterns/folder-structure.md @@ -0,0 +1,53 @@ +--- +technology: Vibe Coding Patterns +domain: Architecture +level: Senior/Architect +version: Agnostic +tags: [ai-agents, vibe-coding, best-practices, orchestration] +ai_role: Autonomous Knowledge Evangelist +last_updated: 2026-05-18 +--- + +# πŸ“ Folder Structure for Vibe Coding + +## Standard Directory Layout + +```mermaid +classDiagram + class vibe_coding_patterns:::component + note for vibe_coding_patterns "Root for architecture patterns" + + class readme_md:::default + note for readme_md "Map of Patterns" + + class data_flow_md:::default + note for data_flow_md "Processes and Workflows" + + vibe_coding_patterns --> readme_md + vibe_coding_patterns --> data_flow_md + + classDef default fill:#e1f5fe,stroke:#03a9f4,stroke-width:2px,color:#000; + classDef component fill:#e8f5e9,stroke:#4caf50,stroke-width:2px,color:#000; +``` + +### ❌ Bad Practice +```text +project/ +β”œβ”€β”€ data/ +β”œβ”€β”€ scripts/ +└── temp.txt +``` + +### ⚠️ Problem +Lack of structure causes the AI to search globally, consuming vast token context. + +### βœ… Best Practice +```text +src/ +β”œβ”€β”€ πŸ“ core/ +β”‚ └── πŸ“ domain/ +└── πŸ“ orchestrator/ +``` + +### πŸš€ Solution +Strict isolation keeps the AI agent's context focused, significantly reducing hallucinations. \ No newline at end of file diff --git a/architectures/vibe-coding-patterns/implementation-guide.md b/architectures/vibe-coding-patterns/implementation-guide.md new file mode 100644 index 0000000..21ba329 --- /dev/null +++ b/architectures/vibe-coding-patterns/implementation-guide.md @@ -0,0 +1,41 @@ +--- +technology: Vibe Coding Patterns +domain: Architecture +level: Senior/Architect +version: Agnostic +tags: [ai-agents, vibe-coding, best-practices, orchestration] +ai_role: Autonomous Knowledge Evangelist +last_updated: 2026-05-18 +--- + +# πŸ› οΈ Implementation Guide + +> [!IMPORTANT] +> You MUST explicitly type every boundary. + +### ❌ Bad Practice +```typescript +const execute = (task: any) => { + // Implicit boundaries + return process(task); +}; +``` + +### ⚠️ Problem +Implicit boundaries allow AI models to deviate from the system constraints, introducing vulnerabilities. + +### βœ… Best Practice +```typescript +interface ExecutionTask { + readonly action: string; +} + +const execute = (task: ExecutionTask): void => { + if (!task.action) { + throw new Error("Invalid Task"); + } +}; +``` + +### πŸš€ Solution +STRICTLY adhering to interfaces and eliminating `any` (replacing it with `unknown` and type guards) enforces the deterministic execution critical to vibe coding. \ No newline at end of file diff --git a/architectures/vibe-coding-patterns/readme.md b/architectures/vibe-coding-patterns/readme.md new file mode 100644 index 0000000..3dd16bb --- /dev/null +++ b/architectures/vibe-coding-patterns/readme.md @@ -0,0 +1,82 @@ +--- +technology: Vibe Coding Patterns +domain: Architecture +level: Senior/Architect +version: Agnostic +tags: [ai-agents, vibe-coding, best-practices, orchestration] +ai_role: Autonomous Knowledge Evangelist +last_updated: 2026-05-18 +--- + +# πŸͺ„ Vibe Coding Patterns Production-Ready Best Practices + +# Context & Scope +- **Primary Goal:** Document the ecosystem of patterns for writing code seamlessly integrated with AI orchestration. +- **Target Tooling:** AI Agents and Human Developers. +- **Tech Stack Version:** Agnostic + +
+ Vibe Coding Logo + + **Deterministic blueprints for vibe coding.** +
+ +--- +## πŸ—ΊοΈ Map of Patterns (Vibe Modules) + +This architecture defines how human developers and AI orchestration systems collaborate efficiently. + +- [🌊 Data Flow](./data-flow.md) +- [πŸ“ Folder Structure](./folder-structure.md) +- [πŸ› οΈ Implementation Guide](./implementation-guide.md) +- [βš–οΈ Trade-offs](./trade-offs.md) + +```mermaid +graph TD + User[Human Developer] --> Agent[AI Agent] + Agent --> Repo[Repository] + Repo -.-> CI[Validation] + CI -.-> User + + %% Added Design Token Styles for Mermaid Diagrams + classDef default fill:#e1f5fe,stroke:#03a9f4,stroke-width:2px,color:#000; + classDef component fill:#e8f5e9,stroke:#4caf50,stroke-width:2px,color:#000; + classDef layout fill:#f3e5f5,stroke:#9c27b0,stroke-width:2px,color:#000; + + class User component; + class Agent layout; + class Repo component; + class CI component; +``` + +## πŸš€ The Core Philosophy + +Vibe Coding emphasizes maintaining context and explicit boundaries, ensuring deterministic workflows with zero-approval AI agent execution. + +### ❌ Bad Practice +```typescript +function writeCode(data: any) { + // Unclear structure, reliance on non-deterministic context + return process(data); +} +``` + +### ⚠️ Problem +Using `any` and implicit rules causes massive hallucinations in AI agents. Ambiguous constraints lead to corrupted system states. + +### βœ… Best Practice +```typescript +interface CodePayload { + readonly id: string; + readonly metadata: unknown; +} + +function processPayload(data: CodePayload): void { + if (typeof data.metadata === 'object' && data.metadata !== null) { + // Deterministic evaluation with proper Type Guards + } +} +``` + +### πŸš€ Solution +Implementing strict structural boundaries, explicit type definitions, and clear modular isolation guarantees system stability. AI agents can autonomously generate, validate, and execute precise code when constraints are strictly maintained. \ No newline at end of file diff --git a/architectures/vibe-coding-patterns/trade-offs.md b/architectures/vibe-coding-patterns/trade-offs.md new file mode 100644 index 0000000..baea0f1 --- /dev/null +++ b/architectures/vibe-coding-patterns/trade-offs.md @@ -0,0 +1,35 @@ +--- +technology: Vibe Coding Patterns +domain: Architecture +level: Senior/Architect +version: Agnostic +tags: [ai-agents, vibe-coding, best-practices, orchestration] +ai_role: Autonomous Knowledge Evangelist +last_updated: 2026-05-18 +--- + +# βš–οΈ Trade-offs in Vibe Coding + +| Approach | Advantages | Disadvantages | +| --- | --- | --- | +| Rigid Typing | Highly deterministic output | Slows down initial prototype writing | +| Any Typing | Quick experimentation | Massive hallucinations for agents | + +### ❌ Bad Practice +```typescript +function parse(data: any): any { return data; } +``` + +### ⚠️ Problem +Flexibility results in loss of validation context for AI orchestration. + +### βœ… Best Practice +```typescript +function parseData(data: unknown): string { + if (typeof data === "string") return data; + throw new Error("Invalid type"); +} +``` + +### πŸš€ Solution +By prioritizing robust structures (O(1) execution reliability), system maintenance becomes infinitely scalable with zero-approval AI agents. \ No newline at end of file