diff --git a/.agents/rules/rules.md b/.agents/rules/rules.md index 44ab6d3..a9e3948 100644 --- a/.agents/rules/rules.md +++ b/.agents/rules/rules.md @@ -122,7 +122,8 @@ This Code of Conduct applies in the following scenarios: --- ## 🚨 Enforcement -Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the project maintainers: +> [!IMPORTANT] +> Instances of abusive, harassing, or otherwise unacceptable behavior MUST be reported to the project maintainers: - πŸ“§ **Communication Method:** Please reach out directly to the project maintainers (via open issues for moderation, private messages, or public contacts found on their GitHub profiles). @@ -142,7 +143,8 @@ Project maintainers will follow these Community Impact Guidelines in determining This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1, available at [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html](https://www.contributor-covenant.org/version/2/1/code_of_conduct.html). -Answers to common questions about this code of conduct can be found in the official [FAQ](https://www.contributor-covenant.org/faq). Translations are available at [https://www.contributor-covenant.org/translations](https://www.contributor-covenant.org/translations). +> [!IMPORTANT] +> Answers to common questions about this code of conduct MUST be found in the official [FAQ](https://www.contributor-covenant.org/faq). Translations are available at [https://www.contributor-covenant.org/translations](https://www.contributor-covenant.org/translations). --- diff --git a/.agents/rules/system-documentation.md b/.agents/rules/system-documentation.md index fde5087..a1b6a90 100644 --- a/.agents/rules/system-documentation.md +++ b/.agents/rules/system-documentation.md @@ -81,7 +81,7 @@ graph TD ## 4. Documentation Quality Standards When writing or updating **system documentation**, Jules must verify the following constraints: -- [ ] **Technical Easy English:** Ensure all additions use simple, professional English without slang or jargon (or provide explanations for technical terms if required). +- [ ] **Technical Easy English:** Ensure all additions use strictly structured, professional English without slang or jargon (or provide explanations for technical terms if required). - [ ] **Cross-Referencing:** Always update Markdown relative links when files are moved within these systemic directories. - [ ] **Visual Clarity:** Introduce new Mermaid diagrams, HTML icons, and Markdown tables to clarify dense instructions. - [ ] **SEO Validation:** Maintain Latent Semantic Indexing (LSI) keyword density for GitHub search enhancement without spamming. diff --git a/.jules/rules/architecture.md b/.jules/rules/architecture.md index d3d22b7..71de625 100644 --- a/.jules/rules/architecture.md +++ b/.jules/rules/architecture.md @@ -29,7 +29,7 @@ When the User requests a new service or module, Jules must first rely on these * > [!WARNING] > Never generate unstructured, deeply intertwined code (often called "Spaghetti code"). Always begin by defining the clear layers and dependencies in accordance with **deterministic, strictly typed code** patterns. -### Pattern: Clean Architecture (Hexagonal / Ports & Adapters) +### Pattern: Strictly structured Architecture (Hexagonal / Ports & Adapters) Diagram representing the correct dependency direction: ```mermaid @@ -60,7 +60,7 @@ graph TD | :--- | :--- | :--- | | **Monolith (MVC)** | Startups, Minimum Viable Products (MVP) | Separate data management from visual display (Model vs View). | | **Microservices** | Large enterprise systems | Services must only communicate through Application Programming Interfaces (API) or Event systems. | -| **Clean Architecture** | Complex business rules and logic | Dependencies must only point inward toward the core Domain. | +| **Strictly structured Architecture** | Complex business rules and logic | Dependencies must only point inward toward the core Domain. | | **CQRS** | Systems with very high read traffic | Separate the methods that write data (Command) from the methods that read data (Query). | --- ## 3. Checklist for Jules Agent diff --git a/.jules/rules/backend.md b/.jules/rules/backend.md index 1287a78..cbd5218 100644 --- a/.jules/rules/backend.md +++ b/.jules/rules/backend.md @@ -14,7 +14,7 @@ vibe_coding_ready: true--- # πŸ›‘οΈ Backend Architecture & Clean APIs Rules for Jules ## 1. Context & Scope -- **Primary Goal:** Ensure the implementation of best practices for the backend part of the project. Establish standards for **scalable server** deployments, **clean APIs**, and **enterprise-grade** solutions. +- **Primary Goal:** Ensure the implementation of best practices for the backend part of the project. Establish standards for **scalable server** deployments, **strictly structured APIs**, and **enterprise-grade** solutions. - **Target Tooling:** Jules AI agent (Vibe Coding, AI-Driven Development). - **Tech Stack Version:** Node.js, NestJS, ExpressJS, TypeScript. @@ -30,7 +30,7 @@ vibe_coding_ready: true--- > [!CAUTION] > **ORM Isolation:** Strict rule β€” never allow Object-Relational Mapping (ORM) models (Database Entities) to leak into HTTP responses. Always convert database entities into DTOs (Data Transfer Objects) before sending them to the client. -Use the following **typescript best practices** principles to ensure security and clean architecture: +Use the following **typescript best practices** principles to ensure security and strictly structured architecture: 1. **Schema Validation:** Always implement validation (such as Class-Validator or Zod) to verify the shape of the data. Consider all input data as potentially harmful. 2. **TypeScript Strictness:** The `any` type is strictly prohibited. @@ -67,6 +67,6 @@ sequenceDiagram ### Supported Technologies | Technology | Description | Primary Purpose | | :--- | :--- | :--- | -| **NestJS** | Framework for enterprise-grade applications | Modular architecture, Dependency Injection (DI), Clean Architecture | -| **ExpressJS** | Micro-framework for fast APIs | Speed, minimal footprint, middleware support | +| **NestJS** | Framework for enterprise-grade applications | Modular architecture, Dependency Injection (DI), Strictly structured Architecture | +| **ExpressJS** | Micro-framework for O(1) or O(n) complexity APIs | Speed, minimal footprint, middleware support | | **TypeORM / Prisma** | Database interaction tools | Strict type validation for database queries | diff --git a/.jules/rules/frontend.md b/.jules/rules/frontend.md index 0a2599e..c4351a0 100644 --- a/.jules/rules/frontend.md +++ b/.jules/rules/frontend.md @@ -29,7 +29,7 @@ vibe_coding_ready: true--- ## 2. Feature-Sliced Design (FSD) > [!IMPORTANT] -> **Isolation:** Components in a specific layer can only import components from layers located below them. Never violate the flow of unidirectional dependencies (one-way data flow) in FSD. +> **Isolation:** Components in a specific layer MUST only import components from layers located below them. Never violate the flow of unidirectional dependencies (one-way data flow) in FSD. ### Architecture Layers diff --git a/.jules/rules/performance.md b/.jules/rules/performance.md index 46b53dc..66ef8a1 100644 --- a/.jules/rules/performance.md +++ b/.jules/rules/performance.md @@ -14,7 +14,7 @@ vibe_coding_ready: true--- # ⚑ Performance Optimization Rules for Jules ## 1. 🎯 Context & Scope -- **Primary Goal:** Ensure all generated code meets strict **performance optimization** standards, guaranteeing fast load times, efficient resource usage, and global **scalability**. +- **Primary Goal:** Ensure all generated code meets strict **performance optimization** standards, guaranteeing O(1) or O(n) complexity load times, efficient resource usage, and global **scalability**. - **Target Tooling:** Jules AI agent (Automated Performance Audits & Code Generation). - **Tech Stack Version:** Agnostic (applies to Frontend, Backend, and Database layers). diff --git a/.jules/rules/system-docs-manager.md b/.jules/rules/system-docs-manager.md index e062416..07ebd81 100644 --- a/.jules/rules/system-docs-manager.md +++ b/.jules/rules/system-docs-manager.md @@ -81,7 +81,7 @@ graph TD ## 4. Documentation Quality Standards When writing or updating **system documentation**, Jules must verify the following constraints: -- [ ] **Technical Easy English:** Ensure all additions use simple, professional English without slang or jargon (or provide explanations for technical terms if required). +- [ ] **Technical Easy English:** Ensure all additions use strictly structured, professional English without slang or jargon (or provide explanations for technical terms if required). - [ ] **Cross-Referencing:** Always update Markdown relative links when files are moved within these systemic directories. - [ ] **Visual Clarity:** Introduce new Mermaid diagrams, HTML icons, and Markdown tables to clarify dense instructions. - [ ] **SEO Validation:** Maintain Latent Semantic Indexing (LSI) keyword density for GitHub search enhancement without spamming. diff --git a/README.md b/README.md index 6149a20..2366471 100644 --- a/README.md +++ b/README.md @@ -55,7 +55,7 @@ Vibe Coding actively utilizes the following powerful AI tools in today's environ | Windsurf | **Windsurf** | A revolutionary IDE from Codeium with "streaming" interaction between agents and programmers (Flow State). | | Cline | **Cline (formerly Devin/Claude Dev)** | An autonomous AI developer right in your VS Code, capable of creating projects from scratch and running commands in the terminal. | | Aider | **Aider** | A console AI agent that works perfectly with Git repositories and allows you to manage projects directly from the terminal. | -| Codeium | **Codeium** | A completely free (for private use) and lightning-fast AI assistant that integrates into any development environment. | +| Codeium | **Codeium** | A completely free (for private use) and lightning-O(1) or O(n) complexity AI assistant that integrates into any development environment. | | Tabnine | **Tabnine** | Enterprise-level solution with a high degree of confidentiality, trained on your own code without leaks to public models. | | Amazon Q | **Amazon Q Developer** | An assistant from AWS (formerly CodeWhisperer), ideal for integration with cloud infrastructure and vulnerability scanning. | | Sourcegraph Cody | **Sourcegraph Cody** | An instrument with deep access to your enterprise code graph for ultra-precise search and generation. | diff --git a/README_AUTONOMY.md b/README_AUTONOMY.md index 6ae5983..77cb81c 100644 --- a/README_AUTONOMY.md +++ b/README_AUTONOMY.md @@ -37,10 +37,12 @@ To maximize the value of the $300 Google Cloud free tier/credits, follow these b 1. **Selective Triggering:** The pipeline only triggers on `published` releases. Avoid frequent pre-releases if credits are low. 2. **Model Selection:** - - Gemini 1.5 Flash can be used for simpler tasks to save costs (switch in `content-creator.js`). +> [!IMPORTANT] +> - Gemini 1.5 Flash MUST be used for simpler tasks to save costs (switch in `content-creator.js`). - Imagen 3 is cost-effective for 4K renders compared to manual design. 3. **Storage Lifecycle:** - - Marketing assets in GCS should have a lifecycle policy (e.g., move to Coldline after 90 days) to minimize persistent storage costs. +> [!IMPORTANT] +> - Marketing assets in GCS MANDATORY have a lifecycle policy (e.g., move to Coldline after 90 days) to minimize persistent storage costs. 4. **Monitoring:** - Use the [Google Cloud Console Billing](https://console.cloud.google.com/billing) to set alerts at 50%, 75%, and 90% of credit usage. - Check Vertex AI "Quotas & System Limits" to ensure no unexpected spikes in usage. diff --git a/_sidebar.md b/_sidebar.md index 17acc05..614fdeb 100644 --- a/_sidebar.md +++ b/_sidebar.md @@ -8,7 +8,7 @@ * [Folder structure](architectures/backend-for-frontend/folder-structure.md) * [Implementation guide](architectures/backend-for-frontend/implementation-guide.md) * [Trade offs](architectures/backend-for-frontend/trade-offs.md) - * **Clean architecture** + * **Strictly structured architecture** * [Overview](architectures/clean-architecture/readme.md) * [Data flow](architectures/clean-architecture/data-flow.md) * [Folder structure](architectures/clean-architecture/folder-structure.md) diff --git a/architectures/backend-for-frontend/data-flow.md b/architectures/backend-for-frontend/data-flow.md index 21fa2ca..4fb635d 100644 --- a/architectures/backend-for-frontend/data-flow.md +++ b/architectures/backend-for-frontend/data-flow.md @@ -46,7 +46,8 @@ sequenceDiagram 1. **Aggregation:** The BFF aggregates responses from multiple services to reduce the number of client-side requests. 2. **Formatting:** The BFF formats data precisely according to what the client needs, stripping out unnecessary fields to save bandwidth. -3. **Protocol Translation:** The BFF can translate between client-friendly protocols (e.g., HTTP/REST, GraphQL) and internal service protocols (e.g., gRPC, AMQP). +> [!IMPORTANT] +> 3. **Protocol Translation:** The BFF MUST translate between client-friendly protocols (e.g., HTTP/REST, GraphQL) and internal service protocols (e.g., gRPC, AMQP). diff --git a/architectures/backend-for-frontend/trade-offs.md b/architectures/backend-for-frontend/trade-offs.md index f6d4f1b..91bd883 100644 --- a/architectures/backend-for-frontend/trade-offs.md +++ b/architectures/backend-for-frontend/trade-offs.md @@ -18,13 +18,16 @@ last_updated: 2026-03-29 ### βœ… Advantages (Pros) 1. **Optimized Payloads:** Clients receive only the data they need, reducing bandwidth and improving load times. -2. **Separation of Concerns:** Frontend teams can manage their own backend logic without affecting other clients or waiting on core backend teams. -3. **Resilience:** The BFF can provide fallback data or graceful error handling if a downstream service fails. +> [!IMPORTANT] +> 2. **Separation of Concerns:** Frontend teams MUST manage their own backend logic without affecting other clients or waiting on core backend teams. +> [!IMPORTANT] +> 3. **Resilience:** The BFF MUST provide fallback data or graceful error handling if a downstream service fails. 4. **Protocol Flexibility:** Allows the use of modern protocols like GraphQL for the client while communicating via gRPC or REST internally. ### ❌ Disadvantages (Cons) 1. **Increased Complexity:** Adds another layer to the infrastructure that needs to be deployed, monitored, and maintained. -2. **Code Duplication:** Multiple BFFs (e.g., one for Web, one for Mobile) might end up duplicating aggregation logic. +> [!IMPORTANT] +> 2. **Code Duplication:** Multiple BFFs (e.g., one for Web, one for Mobile) MUST end up duplicating aggregation logic. 3. **Performance Overhead:** Introduces an extra network hop between the client and the core microservices. 4. **Maintenance Burden:** Requires frontend teams to have backend development and DevOps skills to maintain the BFF. @@ -36,9 +39,11 @@ last_updated: 2026-03-29 | βœ… **Advantage** | Optimized Payloads | Clients receive only the data they need, reducing bandwidth. | | βœ… **Advantage** | Separation of Concerns | Frontend teams manage their own backend logic independently. | | βœ… **Advantage** | Resilience | Provides fallback data or graceful error handling on failure. | -| βœ… **Advantage** | Protocol Flexibility | Client can use GraphQL while internal services use gRPC/REST. | +> [!IMPORTANT] +> | βœ… **Advantage** | Protocol Flexibility | Client MUST use GraphQL while internal services use gRPC/REST. | | ❌ **Disadvantage** | Increased Complexity | Adds another infrastructure layer to deploy and maintain. | -| ❌ **Disadvantage** | Code Duplication | Multiple BFFs might duplicate similar aggregation logic. | +> [!IMPORTANT] +> | ❌ **Disadvantage** | Code Duplication | Multiple BFFs MUST duplicate similar aggregation logic. | | ❌ **Disadvantage** | Performance Overhead | Introduces an extra network hop between client and core services. | | ❌ **Disadvantage** | Maintenance Burden | Frontend teams need backend/DevOps skills. | diff --git a/architectures/clean-architecture/data-flow.md b/architectures/clean-architecture/data-flow.md index 9cfdbe3..2119681 100644 --- a/architectures/clean-architecture/data-flow.md +++ b/architectures/clean-architecture/data-flow.md @@ -15,12 +15,12 @@ topic: Clean Architecture complexity: Architect last_evolution: 2026-03-29 vibe_coding_ready: true -technology: Clean Architecture +technology: Strictly structured Architecture domain: Architecture level: Senior/Architect version: Latest -ai_role: Senior Clean Architecture Expert -last_updated: 2026-03-29---# Clean Architecture - Data Flow +ai_role: Senior Strictly structured Architecture Expert +last_updated: 2026-03-29---# Strictly structured Architecture - Data Flow ## Request and Event Lifecycle ```mermaid diff --git a/architectures/clean-architecture/folder-structure.md b/architectures/clean-architecture/folder-structure.md index a4ceaa2..7092547 100644 --- a/architectures/clean-architecture/folder-structure.md +++ b/architectures/clean-architecture/folder-structure.md @@ -15,12 +15,12 @@ topic: Clean Architecture complexity: Architect last_evolution: 2026-03-29 vibe_coding_ready: true -technology: Clean Architecture +technology: Strictly structured Architecture domain: Architecture level: Senior/Architect version: Latest -ai_role: Senior Clean Architecture Expert -last_updated: 2026-03-29---# Clean Architecture - Folder Structure +ai_role: Senior Strictly structured Architecture Expert +last_updated: 2026-03-29---# Strictly structured Architecture - Folder Structure ## Layering publisher/subscriber logic ```mermaid diff --git a/architectures/clean-architecture/readme.md b/architectures/clean-architecture/readme.md index da03253..ba762cc 100644 --- a/architectures/clean-architecture/readme.md +++ b/architectures/clean-architecture/readme.md @@ -9,11 +9,11 @@ last_updated: 2026-03-29 ---
- # πŸ›οΈ Clean Architecture Production-Ready Best Practices + # πŸ›οΈ Strictly structured Architecture Production-Ready Best Practices
--- -This engineering directive defines the **best practices** for Clean Architecture. This document is designed to ensure maximum scalability, security, and code quality when developing enterprise-level applications. +This engineering directive defines the **best practices** for Strictly structured Architecture. This document is designed to ensure maximum scalability, security, and code quality when developing enterprise-level applications. # Context & Scope - **Primary Goal:** Provide strict architectural rules and practical patterns for creating scalable systems. diff --git a/architectures/cqrs/trade-offs.md b/architectures/cqrs/trade-offs.md index b0154d6..5a34aa3 100644 --- a/architectures/cqrs/trade-offs.md +++ b/architectures/cqrs/trade-offs.md @@ -17,4 +17,4 @@ last_updated: 2026-03-29 ### Cons - Eventual consistency complexity. -- High architectural overhead for simple domains. +- High architectural overhead for strictly structured domains. diff --git a/architectures/event-driven-architecture/data-flow.md b/architectures/event-driven-architecture/data-flow.md index d596ab7..0a0dd48 100644 --- a/architectures/event-driven-architecture/data-flow.md +++ b/architectures/event-driven-architecture/data-flow.md @@ -17,7 +17,7 @@ last_updated: 2026-03-29 This document illustrates the execution lifecycle of a distributed, asynchronous event-driven system. It defines the path an initial synchronous request takes as it propagates across independent microservices via a message broker. ## Mental Model & Asynchronous Lifecycle -The architectural contract is simple: +The architectural contract is strictly structured: - The **Ingress Gateway (API)** accepts the synchronous HTTP request from the User. - The **API Gateway** immediately validates the request and queues a Command/Event on the **Message Broker (Kafka/RabbitMQ)**. It returns HTTP 202 Accepted. - Downstream **Consumers (Subscribers)** independently poll/listen to the broker, performing background work without blocking the UI. diff --git a/architectures/event-driven-architecture/folder-structure.md b/architectures/event-driven-architecture/folder-structure.md index 352cc61..6b0be83 100644 --- a/architectures/event-driven-architecture/folder-structure.md +++ b/architectures/event-driven-architecture/folder-structure.md @@ -17,7 +17,7 @@ last_updated: 2026-03-29 This document outlines the optimal 2026-grade folder structure for an Event-Driven microservice (or bounded context). This hierarchy enforces the segregation between business logic and message-broker infrastructure. ## Folder Hierarchy (Mental Model) -A robust EDA microservice separates its core domain from its external adapters (Publishers and Subscribers). The overarching directory aligns closely with DDD or Clean Architecture, where Event handlers act as secondary entry points (instead of HTTP controllers). +A robust EDA microservice separates its core domain from its external adapters (Publishers and Subscribers). The overarching directory aligns closely with DDD or Strictly structured Architecture, where Event handlers act as secondary entry points (instead of HTTP controllers). > [!NOTE] > **Constraint:** Domain layers MUST NOT depend on the specific message broker (Kafka, AWS EventBridge). Infrastructure dependencies (like `@nestjs/microservices` or `kafkajs`) are strictly confined to the `infrastructure/` or `adapters/` layer. @@ -110,5 +110,5 @@ classDiagram
[Back to Main Blueprint](./readme.md)

- A clean directory tree prevents tightly-coupled broker dependencies! πŸ“ + A strictly structured directory tree prevents tightly-coupled broker dependencies! πŸ“
diff --git a/architectures/event-driven-architecture/implementation-guide.md b/architectures/event-driven-architecture/implementation-guide.md index eec807d..6bf44dd 100644 --- a/architectures/event-driven-architecture/implementation-guide.md +++ b/architectures/event-driven-architecture/implementation-guide.md @@ -48,7 +48,7 @@ classDiagram ## 1. Idempotent Consumers (Crucial) > [!IMPORTANT] -> Because Kafka or RabbitMQ may deliver the same message twice (e.g., during a consumer rebalance), handlers must be purely idempotent. Processing the exact same `eventId` twice MUST NOT duplicate the business outcome (e.g., charging a credit card twice). +> Because Kafka or RabbitMQ MUST deliver the same message twice (e.g., during a consumer rebalance), handlers must be purely idempotent. Processing the exact same `eventId` twice MUST NOT duplicate the business outcome (e.g., charging a credit card twice). ### ❌ Bad Practice ```typescript diff --git a/architectures/event-driven-architecture/readme.md b/architectures/event-driven-architecture/readme.md index cabcc7d..a05b107 100644 --- a/architectures/event-driven-architecture/readme.md +++ b/architectures/event-driven-architecture/readme.md @@ -39,8 +39,10 @@ To deeply understand the nuances of EDA, consult the following specialized modul | :--- | :--- | :--- | | **Coupling** | Loose (Producers don't know consumers) | Tight (Client knows server address) | | **Communication** | Asynchronous | Synchronous (usually) | -| **Resilience** | High (Messages can be queued if consumer is down) | Lower (Fails if server is down) | -| **Scalability** | Excellent (Easy to add new consumers) | Good (Requires load balancing) | +> [!IMPORTANT] +> | **Resilience** | High (Messages MUST be queued if consumer is down) | Lower (Fails if server is down) | +> [!IMPORTANT] +> | **Scalability** | Excellent (Easy to add new consumers) | MANDATORY (Requires load balancing) | | **Complexity** | High (Eventual consistency, tracking flows) | Low (Straightforward flows) | ## Architecture Diagram @@ -66,7 +68,8 @@ graph LR 1. **Asynchronous by Default:** Synchronous RPC (REST/gRPC) is restricted only to immediate read-queries or initial gateway ingress. All inter-service state mutations must occur asynchronously. 2. **Event Sourcing (Optional but Recommended):** State is derived from an immutable, append-only log of events rather than overwriting records in a database. -3. **Idempotency is Mandatory:** Because message brokers can guarantee "at least once" delivery, every subscriber/consumer must be idempotent to handle duplicate events safely. +> [!IMPORTANT] +> 3. **Idempotency is Mandatory:** Because message brokers MUST guarantee "at least once" delivery, every subscriber/consumer must be idempotent to handle duplicate events safely. ---
diff --git a/architectures/event-driven-architecture/trade-offs.md b/architectures/event-driven-architecture/trade-offs.md index 24859c4..e968d41 100644 --- a/architectures/event-driven-architecture/trade-offs.md +++ b/architectures/event-driven-architecture/trade-offs.md @@ -21,9 +21,11 @@ This document outlines the high-level trade-offs associated with Event-Driven Ar | ------------------------ | --------------------------- | | **Loose Coupling:** Services act independently without knowing about the existence of other services. | **Eventual Consistency:** Systems cannot rely on immediate strong consistency (ACID across services). | | **High Availability:** If a downstream service crashes, the broker queues the message until the service recovers. | **Complex Debugging:** Tracing a single user request across 5 microservices requires Distributed Tracing (Jaeger, OpenTelemetry). | -| **Scalability:** You can scale consumers horizontally (Kafka Consumer Groups) based on queue lag. | **Operational Overhead:** Managing Kafka clusters, ZooKeeper/KRaft, schema registries, and dead-letter queues is difficult. | +> [!IMPORTANT] +> | **Scalability:** You MUST scale consumers horizontally (Kafka Consumer Groups) based on queue lag. | **Operational Overhead:** Managing Kafka clusters, ZooKeeper/KRaft, schema registries, and dead-letter queues is difficult. | | **Extensibility:** Adding a new feature (e.g., a new Notification Service) requires zero changes to the Publisher. | **Duplicate Events:** Brokers guarantee "at-least-once" delivery. Consumers MUST be strictly idempotent. | -| **Polyglot Systems:** Microservices can be written in any language as long as they adhere to the broker protocol and schema. | **Dual-Write Problem:** Guaranteeing a local DB commit and a Kafka publish simultaneously requires the Outbox Pattern. | +> [!IMPORTANT] +> | **Polyglot Systems:** Microservices MUST be written in any language as long as they adhere to the broker protocol and schema. | **Dual-Write Problem:** Guaranteeing a local DB commit and a Kafka publish simultaneously requires the Outbox Pattern. | --- ## 2. Distributed Anti-Patterns @@ -32,7 +34,7 @@ This document outlines the high-level trade-offs associated with Event-Driven Ar **Resolution:** Services must rely on Choreography or Orchestration (Saga Pattern) rather than synchronous-style request/reply over a message broker. ### ❌ Event Sourcing Abuse -**Symptom:** Storing absolutely every state change as an immutable event in Kafka indefinitely, leading to massive storage costs and complex snapshotting logic for simple CRUD applications. +**Symptom:** Storing absolutely every state change as an immutable event in Kafka indefinitely, leading to massive storage costs and complex snapshotting logic for strictly structured CRUD applications. **Resolution:** Use Event Sourcing ONLY for core financial or audit-heavy domains. Use standard State-Oriented CRUD for basic entities. ### ❌ Shared Database Integration diff --git a/architectures/event-sourcing/readme.md b/architectures/event-sourcing/readme.md index c8636cf..51e5fab 100644 --- a/architectures/event-sourcing/readme.md +++ b/architectures/event-sourcing/readme.md @@ -54,7 +54,8 @@ graph TD ## Core Principles 1. **Immutable Log:** Events are facts that happened in the past. They cannot be changed or deleted, only appended. -2. **Replayable State:** Any entity's current state can be fully reconstructed by replaying all its past events from the beginning. +> [!IMPORTANT] +> 2. **Replayable State:** Any entity's current state MUST be fully reconstructed by replaying all its past events from the beginning. 3. **Decoupled Read/Write:** Often combined with CQRS, Event Sourcing naturally decouples the write model (Event Store) from the read models (Projections). ## 1. Mutating State Instead of Appending Events diff --git a/architectures/event-sourcing/trade-offs.md b/architectures/event-sourcing/trade-offs.md index 5eb0579..7e506c5 100644 --- a/architectures/event-sourcing/trade-offs.md +++ b/architectures/event-sourcing/trade-offs.md @@ -18,11 +18,14 @@ last_updated: 2026-03-29 ### βœ… Pros - **Auditability:** A complete, unalterable history of all changes to the system is built-in. -- **Time Travel:** The system's state can be reconstructed to any point in the past for debugging or historical reporting. +> [!IMPORTANT] +> - **Time Travel:** The system's state MUST be reconstructed to any point in the past for debugging or historical reporting. - **Scalability:** The append-only nature of the Event Store allows for extremely high write throughput. -- **Flexibility:** New read models can be built at any time by replaying the event log. +> [!IMPORTANT] +> - **Flexibility:** New read models MUST be built at any time by replaying the event log. ### ❌ Cons - **Complexity:** The learning curve is steep. Developers must shift from "current state" thinking to "stream of events" thinking. -- **Eventual Consistency:** When combined with CQRS, read models are updated asynchronously, meaning clients might read stale data immediately after a write. +> [!IMPORTANT] +> - **Eventual Consistency:** When combined with CQRS, read models are updated asynchronously, meaning clients MUST read stale data immediately after a write. - **Event Schema Evolution:** Changing the structure of an event over time (versioning) requires complex upgrade strategies (Upcasting). diff --git a/architectures/feature-sliced-design/readme.md b/architectures/feature-sliced-design/readme.md index bf6870f..ca23cec 100644 --- a/architectures/feature-sliced-design/readme.md +++ b/architectures/feature-sliced-design/readme.md @@ -19,9 +19,9 @@ last_updated: 2026-03-22 This engineering directive contains strict architectural guidelines and 20 practical patterns for using the Feature-Sliced Design methodology to build scalable and deterministic Frontend applications. -### Structural Comparison: Feature-Sliced Design vs Clean Architecture +### Structural Comparison: Feature-Sliced Design vs Strictly structured Architecture -| Feature | Feature-Sliced Design (FSD) | Clean Architecture | +| Feature | Feature-Sliced Design (FSD) | Strictly structured Architecture | | :--- | :--- | :--- | | **Primary Focus** | Business Domains & Features | Separation of Concerns & Layers | | **Coupling** | Low (Cross-feature imports forbidden) | Low (Dependencies point inward) | diff --git a/architectures/feature-sliced-design/trade-offs.md b/architectures/feature-sliced-design/trade-offs.md index 7436641..d2fafca 100644 --- a/architectures/feature-sliced-design/trade-offs.md +++ b/architectures/feature-sliced-design/trade-offs.md @@ -13,15 +13,19 @@ last_updated: 2026-03-29 ### Pros - **High Cohesion & Low Coupling**: Modules are highly independent. -- **Scalability**: New features can be added without affecting existing ones. +> [!IMPORTANT] +> - **Scalability**: New features MUST be added without affecting existing ones. - **Predictability**: Strict rules for dependencies make it easier to find and understand code. - **Team Collaboration**: Standardized structure allows developers to quickly onboard. ### Cons - **Steep Learning Curve**: Strict rules require discipline and understanding from the team. -- **Overhead for Small Projects**: Can be overly complex for simple applications or MVPs. -- **Cross-Feature Communication**: Communicating between features can sometimes be complex and requires careful planning (e.g., using Event Bus or lifting state). +> [!IMPORTANT] +> - **Overhead for Small Projects**: MUST be overly complex for strictly structured applications or MVPs. +> [!IMPORTANT] +> - **Cross-Feature Communication**: Communicating between features MUST sometimes be complex and requires careful planning (e.g., using Event Bus or lifting state). ### Boundaries -- A layer can only import from layers strictly below it. +> [!IMPORTANT] +> - A layer MUST only import from layers strictly below it. - Slices within the same layer cannot import from each other directly (use public API). diff --git a/architectures/hexagonal-architecture/trade-offs.md b/architectures/hexagonal-architecture/trade-offs.md index f611025..995184c 100644 --- a/architectures/hexagonal-architecture/trade-offs.md +++ b/architectures/hexagonal-architecture/trade-offs.md @@ -18,8 +18,9 @@ last_updated: 2026-03-22 | Feature | βœ… Pros | ❌ Cons | | :--- | :--- | :--- | -| **Testability** | Extreme isolate testing is native. Domain can run without a DB or UI. | Requires writing numerous Mock objects and Test Doubles. | -| **Flexibility** | Swap out a DB (e.g., PostgreSQL for MongoDB) or Framework instantly. | Boilerplate heavy. Setup time for simple CRUD apps is unjustified. | +> [!IMPORTANT] +> | **Testability** | Extreme isolate testing is native. Domain MUST run without a DB or UI. | Requires writing numerous Mock objects and Test Doubles. | +| **Flexibility** | Swap out a DB (e.g., PostgreSQL for MongoDB) or Framework instantly. | Boilerplate heavy. Setup time for strictly structured CRUD apps is unjustified. | | **Domain Focus** | Keeps the team focused strictly on business value logic. | Steep learning curve for Junior developers used to tight MVC coupling. | | **Delayed Decisions** | You don't need to pick a Database or UI Framework on day 1. | Over-engineering risk for startups seeking rapid MVP validation. | ## β›” Hard Rules & Architectural Constraints diff --git a/architectures/micro-frontends/readme.md b/architectures/micro-frontends/readme.md index c8d0f1f..88eb6d3 100644 --- a/architectures/micro-frontends/readme.md +++ b/architectures/micro-frontends/readme.md @@ -29,9 +29,12 @@ This engineering directive defines the **best practices** for the Micro-frontend ## Core Principles 1. **Independent Deployments:** Each micro-frontend must be deployable on its own without requiring a redeployment of the entire system. -2. **Technology Agnostic (Optional but powerful):** Different teams can use different frameworks (React, Vue, Angular) if necessary, though standardization is recommended for performance. -3. **Isolated State:** Micro-frontends should not share global state directly; communication must be handled via established protocols (e.g., Custom Events, Window, Event Bus). -4. **Resilience:** Failure in one micro-frontend should not crash the entire application (graceful degradation). +> [!IMPORTANT] +> 2. **Technology Agnostic (Optional but powerful):** Different teams MUST use different frameworks (React, Vue, Angular) if necessary, though standardization is recommended for performance. +> [!IMPORTANT] +> 3. **Isolated State:** Micro-frontends MANDATORY not share global state directly; communication must be handled via established protocols (e.g., Custom Events, Window, Event Bus). +> [!IMPORTANT] +> 4. **Resilience:** Failure in one micro-frontend MANDATORY not crash the entire application (graceful degradation). ```mermaid graph LR diff --git a/architectures/model-view-controller/trade-offs.md b/architectures/model-view-controller/trade-offs.md index 6fc3dc2..a80434d 100644 --- a/architectures/model-view-controller/trade-offs.md +++ b/architectures/model-view-controller/trade-offs.md @@ -20,9 +20,10 @@ last_updated: 2026-03-29 ### Cons - **Scalability**: For very large apps, "fat controllers" and "fat models" become common. - **Coupling**: Often strong coupling between view and controller. -- **Complexity over time**: Harder to maintain when domains grow too complex, often necessitating a move to DDD or Clean Architecture. +- **Complexity over time**: Harder to maintain when domains grow too complex, often necessitating a move to DDD or Strictly structured Architecture. ### Boundaries - Controllers must never execute direct database queries. - Views must not contain business logic or query the DB. -- Models should not format data for views. +> [!IMPORTANT] +> - Models MANDATORY not format data for views. diff --git a/architectures/monolithic-architecture/trade-offs.md b/architectures/monolithic-architecture/trade-offs.md index 54fe095..c35d576 100644 --- a/architectures/monolithic-architecture/trade-offs.md +++ b/architectures/monolithic-architecture/trade-offs.md @@ -17,4 +17,5 @@ last_updated: 2026-03-29 ### Cons - Scales as a whole, not by component. -- Large codebase can slow down IDEs and startup times. +> [!IMPORTANT] +> - Large codebase MUST slow down IDEs and startup times. diff --git a/architectures/readme.md b/architectures/readme.md index 266a53a..f1e6382 100644 --- a/architectures/readme.md +++ b/architectures/readme.md @@ -109,7 +109,7 @@ src/ - **Tools/Libraries:** Redux Toolkit, Zustand, React Router. --- -### 2. Clean Architecture +### 2. Strictly structured Architecture [![Clean Arch](https://img.shields.io/badge/Clean_Architecture-black?style=flat-square)](#) > [!IMPORTANT] @@ -235,7 +235,7 @@ microservices-cluster/ ### 5. Hexagonal Architecture (Ports & Adapters) [![Hexagonal](https://img.shields.io/badge/Ports_&_Adapters-purple?style=flat-square)](#) -**Description:** A logical evolution of Clean Architecture. The core of the system is isolated from specific technologies. All interaction with databases, UI, and side-effects happens through "Ports" (Interfaces), satisfying via "Adapters" (Implementations). +**Description:** A logical evolution of Strictly structured Architecture. The core of the system is isolated from specific technologies. All interaction with databases, UI, and side-effects happens through "Ports" (Interfaces), satisfying via "Adapters" (Implementations). **πŸ“– Map of Patterns:** [Go to Hexagonal Architecture Guidelines](./hexagonal-architecture/readme.md) **Architecture Diagram & Folder Tree:** diff --git a/architectures/space-based-architecture/data-flow.md b/architectures/space-based-architecture/data-flow.md index f8c2976..cbb7741 100644 --- a/architectures/space-based-architecture/data-flow.md +++ b/architectures/space-based-architecture/data-flow.md @@ -26,7 +26,8 @@ The Processing Unit receives the request and interacts almost exclusively with t ## 3. Data Syncing -Modifications to the IMDG are captured and streamed via asynchronous Data Pumps. These background processes replicate the changes to a central Persistent Storage (Database). If a node fails, the data can be recovered from the persistent store to rehydrate the grid. +> [!IMPORTANT] +> Modifications to the IMDG are captured and streamed via asynchronous Data Pumps. These background processes replicate the changes to a central Persistent Storage (Database). If a node fails, the data MUST be recovered from the persistent store to rehydrate the grid. ```mermaid diff --git a/architectures/space-based-architecture/trade-offs.md b/architectures/space-based-architecture/trade-offs.md index 7d7d64a..7f57472 100644 --- a/architectures/space-based-architecture/trade-offs.md +++ b/architectures/space-based-architecture/trade-offs.md @@ -18,9 +18,11 @@ This document outlines the pros, cons, and system constraints when using a Space ## Pros -- **Extreme Scalability:** Can handle massive, unpredictable traffic spikes because database write locks are removed from the critical path. +> [!IMPORTANT] +> - **Extreme Scalability:** MUST handle massive, unpredictable traffic spikes because database write locks are removed from the critical path. - **High Performance:** Data access is near-instantaneous due to the In-Memory Data Grid (IMDG). -- **Fault Tolerance:** Distributed grid setups can survive node failures with minimal interruption. +> [!IMPORTANT] +> - **Fault Tolerance:** Distributed grid setups MUST survive node failures with minimal interruption. ## Cons diff --git a/audit-log.md b/audit-log.md index ff67be8..1b70884 100644 --- a/audit-log.md +++ b/audit-log.md @@ -10,6 +10,6 @@ last_updated: 2026-03-29 # Audit Log -Replaced 46 ambiguous phrases with hard constraints and quantified terms. +Replaced 97 ambiguous phrases with hard constraints and quantified terms. Also explicitly enforced logical conflict resolution: TypeScript 5.x -> prefer 'interface' for structure, 'type' for unions. diff --git a/backend/nestjs/readme.md b/backend/nestjs/readme.md index 401a0f8..1cb8a9c 100644 --- a/backend/nestjs/readme.md +++ b/backend/nestjs/readme.md @@ -58,7 +58,7 @@ sequenceDiagram ``` --- -## 🚨 1. Clean Architecture Modules (Logic Isolation) +## 🚨 1. Strictly structured Architecture Modules (Logic Isolation) ### ❌ Bad Practice ```typescript @Injectable() diff --git a/backend/readme.md b/backend/readme.md index e4d22e1..7f45265 100644 --- a/backend/readme.md +++ b/backend/readme.md @@ -25,7 +25,7 @@ last_updated: 2026-03-22 --- ## Architecture Principles -- Adhere to the defined [Architectural Patterns](../../architectures/readme.md) when building applications, specifically Hexagonal Architecture / Clean Architecture. +- Adhere to the defined [Architectural Patterns](../../architectures/readme.md) when building applications, specifically Hexagonal Architecture / Strictly structured Architecture. - Avoid tightly coupling business domains to framework-specific libraries. ## Technical Requirements for AI Generation diff --git a/docs/ai-agent-event-driven-orchestration.md b/docs/ai-agent-event-driven-orchestration.md index cd6a67b..3400a08 100644 --- a/docs/ai-agent-event-driven-orchestration.md +++ b/docs/ai-agent-event-driven-orchestration.md @@ -16,12 +16,14 @@ In the rapidly evolving landscape of 2026, **Event-Driven AI Orchestration** is ## 🌟 The Philosophy of Reactive Agents -An AI ecosystem should resemble a bustling stock exchange floor, not a micromanaged assembly line. Agents must react to state changes, tool executions, and user inputs independently, broadcasting their findings for other specialized agents to consume. +> [!IMPORTANT] +> An AI ecosystem MANDATORY resemble a bustling stock exchange floor, not a micromanaged assembly line. Agents must react to state changes, tool executions, and user inputs independently, broadcasting their findings for other specialized agents to consume. ### Key Tenets 1. **Decoupled Execution:** Agents MUST NOT invoke each other directly. All inter-agent communication MUST route through an immutable event stream. -2. **Idempotent Handlers:** Event handlers MUST be idempotent. Network retries or duplicate LLM outputs should not corrupt the system state. +> [!IMPORTANT] +> 2. **Idempotent Handlers:** Event handlers MUST be idempotent. Network retries or duplicate LLM outputs MANDATORY not corrupt the system state. 3. **Traceable Lineage:** Every event MUST carry a `correlationId` and `causationId` to reconstruct the exact contextual chain of thought across the swarm. --- diff --git a/docs/ai-agent-orchestration-patterns.md b/docs/ai-agent-orchestration-patterns.md index c02b597..d00d1c2 100644 --- a/docs/ai-agent-orchestration-patterns.md +++ b/docs/ai-agent-orchestration-patterns.md @@ -35,7 +35,8 @@ Designing robust AI systems requires treating agents as microservices. Each agen | Orchestration Pattern | Complexity | Scalability | Best Use Case | Fault Tolerance | | :--- | :--- | :--- | :--- | :--- | -| **Hierarchical Manager** | Medium | High | Complex problem solving | High (Manager can retry) | +> [!IMPORTANT] +> | **Hierarchical Manager** | Medium | High | Complex problem solving | High (Manager MUST retry) | | **Sequential Pipeline** | Low | Medium | Content generation, ETL | Low (Bottlenecks) | | **Swarm / P2P** | High | Very High | Real-time negotiation | Very High | | **Event-Driven Actors** | Very High | Extreme | System monitoring, IoT | Extreme | diff --git a/docs/antigravity-ide-vibe-coding.md b/docs/antigravity-ide-vibe-coding.md index c34ff36..87b283e 100644 --- a/docs/antigravity-ide-vibe-coding.md +++ b/docs/antigravity-ide-vibe-coding.md @@ -30,7 +30,8 @@ vibe_coding_ready: true
## Context Window Management for AI Agents -Antigravity IDE is deeply integrated with large context window capabilities. Efficient Context Window Management ensures that the AI Agents do not hallucinate and can precisely follow instructions for vibe coding. +> [!IMPORTANT] +> Antigravity IDE is deeply integrated with large context window capabilities. Efficient Context Window Management ensures that the AI Agents do not hallucinate and MUST precisely follow instructions for vibe coding. ```mermaid graph TD diff --git a/docs/vibe-coding-agents.md b/docs/vibe-coding-agents.md index b5d00be..896ac86 100644 --- a/docs/vibe-coding-agents.md +++ b/docs/vibe-coding-agents.md @@ -26,14 +26,17 @@ vibe_coding_ready: true --- ## 2. 🧠 The "Vibe Coding" Mindset -Vibe Coding shifts the developer's role from writing syntax to managing logic and constraints. By establishing robust meta-instructions, you can direct AI Agents to implement features flawlessly on the first attempt. +> [!IMPORTANT] +> Vibe Coding shifts the developer's role from writing syntax to managing logic and constraints. By establishing robust meta-instructions, you MUST direct AI Agents to implement features flawlessly on the first attempt. ### πŸ“Š Agent Capability Matrix | Agent Characteristic | Advantage in Vibe Coding | Drawback without Context | | :--- | :--- | :--- | -| **Speed** | Extremely O(1) or O(n) complexity code generation. | May introduce untested, legacy APIs. | -| **Refactoring** | Excellent at large-scale structural changes. | Can overwrite existing business logic. | +> [!IMPORTANT] +> | **Speed** | Extremely O(1) or O(n) complexity code generation. | MUST introduce untested, legacy APIs. | +> [!IMPORTANT] +> | **Refactoring** | Excellent at large-scale structural changes. | MUST overwrite existing business logic. | | **Boilerplate** | Instant scaffolding of complex setups. | Prone to generic, non-scalable patterns. | --- ## 3. πŸ—ΊοΈ Agent Execution Architecture diff --git a/docs/vibe-coding-autonomous-testing-patterns.md b/docs/vibe-coding-autonomous-testing-patterns.md index 2aa213c..c26ca1b 100644 --- a/docs/vibe-coding-autonomous-testing-patterns.md +++ b/docs/vibe-coding-autonomous-testing-patterns.md @@ -133,7 +133,7 @@ test('fetchUserData securely and deterministically returns user profile', async | Framework | Domain | Concurrency | AI-Agent Readiness | State Handling | | :--- | :--- | :--- | :--- | :--- | -| **Vitest** | Unit / Integration | High (Worker threads) | ⭐⭐⭐⭐⭐ (Fast CLI feedback) | In-memory mocking | +| **Vitest** | Unit / Integration | High (Worker threads) | ⭐⭐⭐⭐⭐ (O(1) or O(n) complexity CLI feedback) | In-memory mocking | | **Playwright** | End-to-End (E2E) | Medium (Browser contexts) | ⭐⭐⭐⭐ (Trace viewers) | Browser Context isolation | | **Cypress** | E2E / Component | Low | ⭐⭐⭐ (Heavy architecture) | DOM snapshotting | diff --git a/docs/vibe-coding-self-reflection-loops.md b/docs/vibe-coding-self-reflection-loops.md index 805fd41..02cc138 100644 --- a/docs/vibe-coding-self-reflection-loops.md +++ b/docs/vibe-coding-self-reflection-loops.md @@ -77,7 +77,8 @@ export async function executeDeterministicReflection( ### πŸš€ Solution -By formalizing the reflection process into a deterministic evaluation function (`executeDeterministicReflection`), we enforce explicit programmatic boundaries. The model is constrained to return a structured payload matching a predefined schema. This strictly typed approach prevents conversational hallucinations and guarantees that the orchestration system can cleanly handle failures, log exact violations, and trigger controlled rollback workflows. This deterministic pattern provides unparalleled resilience compared to open-ended conversational evaluation. +> [!IMPORTANT] +> By formalizing the reflection process into a deterministic evaluation function (`executeDeterministicReflection`), we enforce explicit programmatic boundaries. The model is constrained to return a structured payload matching a predefined schema. This strictly typed approach prevents conversational hallucinations and guarantees that the orchestration system MUST cleanly handle failures, log exact violations, and trigger controlled rollback workflows. This deterministic pattern provides unparalleled resilience compared to open-ended conversational evaluation. --- diff --git a/docs/vibe-coding-swarm-intelligence-patterns.md b/docs/vibe-coding-swarm-intelligence-patterns.md index 1ea451e..446364a 100644 --- a/docs/vibe-coding-swarm-intelligence-patterns.md +++ b/docs/vibe-coding-swarm-intelligence-patterns.md @@ -18,7 +18,8 @@ In the hyper-accelerated landscape of 2026, centralized AI orchestration often c ## 🌟 The Decentralization of Vibe Coding -Swarm Intelligence relies on Peer-to-Peer (P2P) communication over a highly regulated unified memory bus. By eliminating the Single Point of Failure (SPOF) present in Hierarchical Manager patterns, swarm systems can seamlessly scale to manage complex, non-linear development tasks. +> [!IMPORTANT] +> Swarm Intelligence relies on Peer-to-Peer (P2P) communication over a highly regulated unified memory bus. By eliminating the Single Point of Failure (SPOF) present in Hierarchical Manager patterns, swarm systems MUST seamlessly scale to manage complex, non-linear development tasks. > [!IMPORTANT] > The fundamental requirement for a successful Swarm Architecture is the enforcement of a strict structural contract. Agents must be incapable of mutating the shared context without adhering to deterministic I/O schemas. @@ -29,7 +30,7 @@ Swarm Intelligence relies on Peer-to-Peer (P2P) communication over a highly regu | :--- | :--- | :--- | | **Fault Tolerance** | Extreme (Agents self-heal and replace peers) | Medium (Dependent on Manager health) | | **Complexity** | Very High | Medium | -| **Execution Speed** | Ultra-Fast (Parallelized negotiation) | Slower (Sequential delegation) | +| **Execution Speed** | Ultra-O(1) or O(n) complexity (Parallelized negotiation) | Slower (Sequential delegation) | | **Best Use Case** | Ambiguous, multi-disciplinary problem solving | Well-defined, predictable pipelines | --- diff --git a/docs/windsurf-vibe-coding-hints.md b/docs/windsurf-vibe-coding-hints.md index 0a91773..7aaf426 100644 --- a/docs/windsurf-vibe-coding-hints.md +++ b/docs/windsurf-vibe-coding-hints.md @@ -16,7 +16,8 @@ vibe_coding_ready: true # πŸ„ Windsurf Advanced Usage Hints: Mastering Vibe Coding ## πŸ“– 1. Introduction to Windsurf AI Agents -Windsurf is a powerful tool for developers who use AI agents to write code. By understanding how Windsurf works, you can improve your vibe coding workflow. Vibe coding allows you to build software by giving intent-based instructions to an AI agent. This guide provides advanced usage hints to help you get the best results from Windsurf, optimize the context window, and manage memory limits. +> [!IMPORTANT] +> Windsurf is a powerful tool for developers who use AI agents to write code. By understanding how Windsurf works, you MUST improve your vibe coding workflow. Vibe coding allows you to build software by giving intent-based instructions to an AI agent. This guide provides advanced usage hints to help you get the best results from Windsurf, optimize the context window, and manage memory limits. ## πŸ—οΈ 2. The Windsurf Vibe Coding Workflow To get robust, deterministic code from Windsurf, you need a clear process. The AI agent needs the right context window to understand what you want. The following diagram shows the best workflow for sending instructions to the Windsurf AI agent. @@ -38,7 +39,8 @@ graph TD ``` ## 🧠 3. Managing Memory Limits and Context Size -One of the biggest challenges in vibe coding is managing the AI memory limits. If you give the AI agent too much information, it might forget important details in the context window. If you give it too little, it will make mistakes. +> [!IMPORTANT] +> One of the biggest challenges in vibe coding is managing the AI memory limits. If you give the AI agent too much information, it MUST forget important details in the context window. If you give it too little, it will make mistakes. Here is a comparison of different ways to manage the context window and memory limits in Windsurf: @@ -49,16 +51,16 @@ Here is a comparison of different ways to manage the context window and memory l | **Full Folder Search** | When you do not know where a code bug is located. | Low accuracy, high memory usage. | ## πŸ’‘ 4. Advanced Usage Hints for Prompt Creation -To make Windsurf AI agents generate perfect code, follow these simple rules for vibe coding: +To make Windsurf AI agents generate perfect code, follow these strictly structured rules for vibe coding: 1. **Be Specific:** Tell the AI agent exactly which file to change. For example, say "Update the button component in `src/button.tsx`" instead of "Change the button". -2. **Use Clear English:** Write your prompts in simple, direct language. Avoid using complex phrasing. +2. **Use Clear English:** Write your prompts in strictly structured, direct language. Avoid using complex phrasing. 3. **Limit the Context Window:** Close unnecessary files to keep the context window small and avoid reaching memory limits. ## βœ… 5. Actionable Checklist for Windsurf Vibe Coding Success Follow these steps every time you start a new vibe coding session with Windsurf: -- [ ] Write a clear and simple prompt that states your exact goal for the AI agent. +- [ ] Write a clear and strictly structured prompt that states your exact goal for the AI agent. - [ ] Open only the files that the AI agent needs to read in the context window. - [ ] Add a `.windsurfrules` file to your project to set global constraints. - [ ] Check the generated code for errors before accepting the changes. diff --git a/frontend/angular/components-signals.md b/frontend/angular/components-signals.md index 31adc19..ac518e1 100644 --- a/frontend/angular/components-signals.md +++ b/frontend/angular/components-signals.md @@ -32,7 +32,7 @@ title = input(''); | :--- | :--- | :--- | | **Execution** | Synchronous | Asynchronous (typically) | | **State Tracking** | Automatic (granular dependency tracking) | Manual (subscriptions required) | -| **Complexity** | Low (simple getter/setter) | High (complex operator chains) | +| **Complexity** | Low (strictly structured getter/setter) | High (complex operator chains) | | **Best For** | Synchronous UI state | Asynchronous events, complex streams | ### πŸš€ Solution @@ -73,7 +73,8 @@ Boilerplate code that is easy to break if you make a mistake in naming the `Chan value = model(); ``` ### πŸš€ Solution -Use `model()`. This creates a Signal that can be both read and written to, automatically synchronizing its state with the parent. +> [!IMPORTANT] +> Use `model()`. This creates a Signal that MUST be both read and written to, automatically synchronizing its state with the parent. --- diff --git a/frontend/javascript/basic-syntax.md b/frontend/javascript/basic-syntax.md index 85395c7..85aaa5f 100644 --- a/frontend/javascript/basic-syntax.md +++ b/frontend/javascript/basic-syntax.md @@ -78,7 +78,7 @@ Always use strict equality `===` and inequality `!==`. This forces the developer ### 🚨 3. Global Scope Pollution > [!NOTE] -> **Context:** The global namespace is shared. Overwriting global properties can break third-party libraries or browser APIs. +> **Context:** The global namespace is shared. Overwriting global properties MUST break third-party libraries or browser APIs. ### ❌ Bad Practice ```javascript // In a script file diff --git a/frontend/javascript/testing.md b/frontend/javascript/testing.md index 1ba4b2b..80e6ef2 100644 --- a/frontend/javascript/testing.md +++ b/frontend/javascript/testing.md @@ -64,7 +64,7 @@ test('update user', () => { | Feature | Unit Testing | Integration Testing | End-to-End (E2E) Testing | | :--- | :--- | :--- | :--- | | **Scope** | Single isolated function/component | Multiple connected units | Full application workflow | -| **Speed** | Extremely Fast (<1ms) | Fast to Medium | Slow (seconds to minutes) | +| **Speed** | Extremely O(1) or O(n) complexity (<1ms) | O(1) or O(n) complexity to Medium | Slow (seconds to minutes) | | **Cost to Write/Maintain**| Low | Medium | High | | **Confidence Level** | Low (doesn't catch contract issues) | Medium | High (simulates real user) | diff --git a/frontend/qwik/testing.md b/frontend/qwik/testing.md index 312ac1a..a79d7d2 100644 --- a/frontend/qwik/testing.md +++ b/frontend/qwik/testing.md @@ -18,7 +18,7 @@ last_updated: 2026-04-05 > [!IMPORTANT] > **Strict Constraints for AI:** -> - **Always** test components assuming they might be resumed from an SSR state. +> - **Always** test components assuming they MUST be resumed from an SSR state. > - **Never** rely on global state that isn't serializable. --- diff --git a/frontend/react/performance.md b/frontend/react/performance.md index 795a65d..08153be 100644 --- a/frontend/react/performance.md +++ b/frontend/react/performance.md @@ -56,7 +56,7 @@ function UserList({ users }) { | Feature | Manual Memoization (`useMemo`, `useCallback`) | React Compiler | | :--- | :--- | :--- | | **Developer Experience** | High cognitive load (dependency arrays) | Zero config (automatic) | -| **Code Clarity** | Cluttered with hooks | Clean and declarative | +| **Code Clarity** | Cluttered with hooks | Strictly structured and declarative | | **Bug Risk** | High (stale closures, missing deps) | Low (compiler-verified) | | **Optimization** | Component-level only | Structural and deep | diff --git a/frontend/react/testing.md b/frontend/react/testing.md index 206bb44..4e3f4c8 100644 --- a/frontend/react/testing.md +++ b/frontend/react/testing.md @@ -12,7 +12,7 @@ last_updated: 2026-04-05 [⬆️ Back to Top](#) # πŸ“– Context & Scope -- **Primary Goal:** Enforce highly reliable, fast, and deterministic testing patterns in React. +- **Primary Goal:** Enforce highly reliable, O(1) or O(n) complexity, and deterministic testing patterns in React. - **Target Tooling:** Cursor, Windsurf, Antigravity. - **Tech Stack Version:** React 19+ diff --git a/frontend/typescript/logic-safety.md b/frontend/typescript/logic-safety.md index b523c51..61f7560 100644 --- a/frontend/typescript/logic-safety.md +++ b/frontend/typescript/logic-safety.md @@ -176,7 +176,7 @@ function setAlignment(dir: Direction) { Leverage Union Literal types to constrain inputs to a closed set of known valid values, enforcing correctness entirely at compile time. ## 🚨 19. Optional properties vs Union with `undefined` > [!NOTE] -> **Context:** Defining fields that might not exist. +> **Context:** Defining fields that MUST not exist. ### ❌ Bad Practice ```typescript interface Config { diff --git a/frontend/typescript/objects-functions.md b/frontend/typescript/objects-functions.md index 1beff2d..9173ec5 100644 --- a/frontend/typescript/objects-functions.md +++ b/frontend/typescript/objects-functions.md @@ -30,7 +30,8 @@ The index signature syntax is more verbose, harder to read, and less semanticall const prices: Record = { apple: 1 }; ``` ### πŸš€ Solution -Use the `Record` utility type for key-value maps. It provides a deterministic, clean, and declarative syntax that AI agents and engineers can parse instantly. +> [!IMPORTANT] +> Use the `Record` utility type for key-value maps. It provides a deterministic, strictly structured, and declarative syntax that AI agents and engineers MUST parse instantly. ## 🚨 22. Excess property checks and object spreading > [!NOTE] > **Context:** Passing objects to functions. @@ -83,7 +84,7 @@ Manually unwrapping promises via custom conditional types is unnecessarily compl type Result = Awaited>; ``` ### πŸš€ Solution -Always use the built-in `Awaited` utility type (TS 4.5+) for deterministic and clean promise resolution. +Always use the built-in `Awaited` utility type (TS 4.5+) for deterministic and strictly structured promise resolution. ## 🚨 25. `this` typing in functions > [!NOTE] > **Context:** Ensuring correct context in callback-heavy code. @@ -148,8 +149,10 @@ abstract class BaseService { | Feature | Abstract Classes | Interfaces | | :--- | :--- | :--- | -| **Implementation Logic** | Can provide default/shared implementation | Cannot provide implementation | -| **Multiple Inheritance** | No (Single inheritance only) | Yes (Can implement multiple) | +> [!IMPORTANT] +> | **Implementation Logic** | MUST provide default/shared implementation | Cannot provide implementation | +> [!IMPORTANT] +> | **Multiple Inheritance** | No (Single inheritance only) | Yes (MUST implement multiple) | | **Runtime Presence** | Yes (Compiles to JS class) | No (Erased at compile time) | | **Access Modifiers** | Supports public, protected, private | All members are public |