From f29a4be8fbc18ed00b6d4c7f5482fdc65ac37e35 Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Sun, 3 May 2026 08:11:17 +0000 Subject: [PATCH] [refactor: anti-hallucination-harden] Co-authored-by: beginwebdev2002 <102213457+beginwebdev2002@users.noreply.github.com> --- README_AUTONOMY.md | 6 ++++-- _sidebar.md | 3 ++- architectures/backend-for-frontend/data-flow.md | 3 ++- architectures/backend-for-frontend/trade-offs.md | 14 +++++++++----- architectures/clean-architecture/data-flow.md | 15 +++++++++------ .../clean-architecture/folder-structure.md | 15 +++++++++------ .../clean-architecture/implementation-guide.md | 3 ++- architectures/clean-architecture/readme.md | 6 ++++-- architectures/cqrs/trade-offs.md | 3 ++- .../event-driven-architecture/data-flow.md | 3 ++- .../event-driven-architecture/folder-structure.md | 6 ++++-- .../implementation-guide.md | 2 +- architectures/event-driven-architecture/readme.md | 3 ++- .../event-driven-architecture/trade-offs.md | 9 ++++++--- architectures/event-sourcing/readme.md | 3 ++- architectures/event-sourcing/trade-offs.md | 9 ++++++--- architectures/feature-sliced-design/readme.md | 6 ++++-- architectures/feature-sliced-design/trade-offs.md | 11 +++++++---- .../hexagonal-architecture/trade-offs.md | 5 +++-- architectures/micro-frontends/readme.md | 7 ++++--- architectures/model-view-controller/trade-offs.md | 6 ++++-- .../monolithic-architecture/trade-offs.md | 3 ++- architectures/readme.md | 6 ++++-- .../space-based-architecture/data-flow.md | 3 ++- .../space-based-architecture/trade-offs.md | 6 ++++-- audit-log.md | 4 ++++ backend/nestjs/readme.md | 3 ++- docs/ai-agent-event-driven-orchestration.md | 6 ++++-- docs/ai-agent-orchestration-patterns.md | 3 ++- docs/antigravity-ide-vibe-coding.md | 3 ++- docs/vibe-coding-agents.md | 8 +++++--- docs/vibe-coding-autonomous-testing-patterns.md | 3 ++- docs/vibe-coding-self-reflection-loops.md | 3 ++- docs/vibe-coding-swarm-intelligence-patterns.md | 6 ++++-- docs/windsurf-vibe-coding-hints.md | 15 ++++++++++----- frontend/angular/components-signals.md | 6 ++++-- frontend/javascript/basic-syntax.md | 2 +- frontend/javascript/clean-code.md | 3 ++- frontend/javascript/testing.md | 3 ++- frontend/qwik/testing.md | 2 +- frontend/react/performance.md | 3 ++- frontend/react/testing.md | 3 ++- frontend/typescript/logic-safety.md | 2 +- frontend/typescript/objects-functions.md | 11 +++++++---- 44 files changed, 159 insertions(+), 86 deletions(-) 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..e8b19cd 100644 --- a/_sidebar.md +++ b/_sidebar.md @@ -8,7 +8,8 @@ * [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** +> [!IMPORTANT] +> * **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..c742a65 100644 --- a/architectures/backend-for-frontend/trade-offs.md +++ b/architectures/backend-for-frontend/trade-offs.md @@ -18,13 +18,15 @@ 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. +> 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) STRICTLY 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 +38,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 STRICTLY 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..b5d3013 100644 --- a/architectures/clean-architecture/data-flow.md +++ b/architectures/clean-architecture/data-flow.md @@ -9,18 +9,21 @@ last_updated: 2026-03-22 --- --- -description: Vibe coding guidelines and architectural constraints for Clean Architecture within the Architecture domain. -tags: [clean-architecture, architecture, best-practices, architecture] -topic: Clean Architecture +> [!IMPORTANT] +> description: Vibe coding guidelines and architectural constraints for strictly structured Architecture within the Architecture domain. +> tags: [strictly structured-architecture, architecture, best-practices, architecture] +> topic: strictly structured Architecture complexity: Architect last_evolution: 2026-03-29 vibe_coding_ready: true -technology: Clean Architecture +> [!IMPORTANT] +> 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 +> [!IMPORTANT] +> 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..e93eb9c 100644 --- a/architectures/clean-architecture/folder-structure.md +++ b/architectures/clean-architecture/folder-structure.md @@ -9,18 +9,21 @@ last_updated: 2026-03-22 --- --- -description: Vibe coding guidelines and architectural constraints for Clean Architecture within the Architecture domain. -tags: [clean-architecture, architecture, best-practices, architecture] -topic: Clean Architecture +> [!IMPORTANT] +> description: Vibe coding guidelines and architectural constraints for strictly structured Architecture within the Architecture domain. +> tags: [strictly structured-architecture, architecture, best-practices, architecture] +> topic: strictly structured Architecture complexity: Architect last_evolution: 2026-03-29 vibe_coding_ready: true -technology: Clean Architecture +> [!IMPORTANT] +> 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 +> [!IMPORTANT] +> 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/implementation-guide.md b/architectures/clean-architecture/implementation-guide.md index 5fcefe1..71eb154 100644 --- a/architectures/clean-architecture/implementation-guide.md +++ b/architectures/clean-architecture/implementation-guide.md @@ -8,7 +8,8 @@ ai_role: System Architect last_updated: 2026-03-22 --- -# 🛠️ Clean Architecture Implementation Guide +> [!IMPORTANT] +> # 🛠️ strictly structured Architecture Implementation Guide
**Executable blueprints and constraints for AI-agent code generation.** diff --git a/architectures/clean-architecture/readme.md b/architectures/clean-architecture/readme.md index da03253..3788fff 100644 --- a/architectures/clean-architecture/readme.md +++ b/architectures/clean-architecture/readme.md @@ -9,11 +9,13 @@ last_updated: 2026-03-29 ---
- # 🏛️ Clean Architecture Production-Ready Best Practices +> [!IMPORTANT] +> # 🏛️ 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. +> [!IMPORTANT] +> 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..67911f8 100644 --- a/architectures/cqrs/trade-offs.md +++ b/architectures/cqrs/trade-offs.md @@ -17,4 +17,5 @@ last_updated: 2026-03-29 ### Cons - Eventual consistency complexity. -- High architectural overhead for simple domains. +> [!IMPORTANT] +> - High architectural overhead for deterministic domains. diff --git a/architectures/event-driven-architecture/data-flow.md b/architectures/event-driven-architecture/data-flow.md index d596ab7..6700ef7 100644 --- a/architectures/event-driven-architecture/data-flow.md +++ b/architectures/event-driven-architecture/data-flow.md @@ -17,7 +17,8 @@ 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: +> [!IMPORTANT] +> The architectural contract is deterministic: - 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..9030a39 100644 --- a/architectures/event-driven-architecture/folder-structure.md +++ b/architectures/event-driven-architecture/folder-structure.md @@ -17,7 +17,8 @@ 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). +> [!IMPORTANT] +> 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 +111,6 @@ classDiagram
[Back to Main Blueprint](./readme.md)

- A clean directory tree prevents tightly-coupled broker dependencies! 📁 +> [!IMPORTANT] +> 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..383d463 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 STRICTLY 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..77d79b4 100644 --- a/architectures/event-driven-architecture/readme.md +++ b/architectures/event-driven-architecture/readme.md @@ -66,7 +66,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..d1e8f54 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,8 @@ 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. +> [!IMPORTANT] +> **Symptom:** Storing absolutely every state change as an immutable event in Kafka indefinitely, leading to massive storage costs and complex snapshotting logic for deterministic 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..bcadfca 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 STRICTLY 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..027c7f9 100644 --- a/architectures/feature-sliced-design/readme.md +++ b/architectures/feature-sliced-design/readme.md @@ -19,9 +19,11 @@ 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 +> [!IMPORTANT] +> ### Structural Comparison: Feature-Sliced Design vs strictly structured Architecture -| Feature | Feature-Sliced Design (FSD) | Clean Architecture | +> [!IMPORTANT] +> | 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..4cefb52 100644 --- a/architectures/feature-sliced-design/trade-offs.md +++ b/architectures/feature-sliced-design/trade-offs.md @@ -13,15 +13,18 @@ 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 deterministic applications or MVPs. +> - **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..81fd372 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 deterministic 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..dbaf63e 100644 --- a/architectures/micro-frontends/readme.md +++ b/architectures/micro-frontends/readme.md @@ -29,9 +29,10 @@ 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. +> 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). +> 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..26eb6ee 100644 --- a/architectures/model-view-controller/trade-offs.md +++ b/architectures/model-view-controller/trade-offs.md @@ -20,9 +20,11 @@ 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. +> [!IMPORTANT] +> - **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..e3b64e0 100644 --- a/architectures/readme.md +++ b/architectures/readme.md @@ -109,7 +109,8 @@ src/ - **Tools/Libraries:** Redux Toolkit, Zustand, React Router. --- -### 2. Clean Architecture +> [!IMPORTANT] +> ### 2. strictly structured Architecture [![Clean Arch](https://img.shields.io/badge/Clean_Architecture-black?style=flat-square)](#) > [!IMPORTANT] @@ -235,7 +236,8 @@ 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). +> [!IMPORTANT] +> **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..aa147d4 100644 --- a/audit-log.md +++ b/audit-log.md @@ -13,3 +13,7 @@ last_updated: 2026-03-29 Replaced 46 ambiguous phrases with hard constraints and quantified terms. Also explicitly enforced logical conflict resolution: TypeScript 5.x -> prefer 'interface' for structure, 'type' for unions. + + +Replaced 88 ambiguous phrases with hard constraints. +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..02ede60 100644 --- a/backend/nestjs/readme.md +++ b/backend/nestjs/readme.md @@ -58,7 +58,8 @@ sequenceDiagram ``` --- -## 🚨 1. Clean Architecture Modules (Logic Isolation) +> [!IMPORTANT] +> ## 🚨 1. strictly structured Architecture Modules (Logic Isolation) ### ❌ Bad Practice ```typescript @Injectable() 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..cf59835 100644 --- a/docs/vibe-coding-agents.md +++ b/docs/vibe-coding-agents.md @@ -26,14 +26,16 @@ 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. | STRICTLY introduce untested, legacy APIs. | +> | **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..7f3fbd9 100644 --- a/docs/vibe-coding-autonomous-testing-patterns.md +++ b/docs/vibe-coding-autonomous-testing-patterns.md @@ -133,7 +133,8 @@ 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 | +> [!IMPORTANT] +> | **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..0f203a1 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,8 @@ 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) | +> [!IMPORTANT] +> | **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..385ed53 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 STRICTLY 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,19 @@ 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: +> [!IMPORTANT] +> To make Windsurf AI agents generate perfect code, follow these deterministic 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. +> [!IMPORTANT] +> 2. **Use Clear English:** Write your prompts in deterministic, 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. +> [!IMPORTANT] +> - [ ] Write a clear and deterministic 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..33a5cd5 100644 --- a/frontend/angular/components-signals.md +++ b/frontend/angular/components-signals.md @@ -32,7 +32,8 @@ title = input(''); | :--- | :--- | :--- | | **Execution** | Synchronous | Asynchronous (typically) | | **State Tracking** | Automatic (granular dependency tracking) | Manual (subscriptions required) | -| **Complexity** | Low (simple getter/setter) | High (complex operator chains) | +> [!IMPORTANT] +> | **Complexity** | Low (deterministic getter/setter) | High (complex operator chains) | | **Best For** | Synchronous UI state | Asynchronous events, complex streams | ### 🚀 Solution @@ -73,7 +74,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/clean-code.md b/frontend/javascript/clean-code.md index 9b5fcf8..898d5ea 100644 --- a/frontend/javascript/clean-code.md +++ b/frontend/javascript/clean-code.md @@ -8,7 +8,8 @@ ai_role: Senior JavaScript Expert last_updated: 2026-04-05 --- -# 🧹 Clean Code & Logic +> [!IMPORTANT] +> # 🧹 strictly structured code & Logic [⬆️ Back to Top](./readme.md) diff --git a/frontend/javascript/testing.md b/frontend/javascript/testing.md index 1ba4b2b..c91a795 100644 --- a/frontend/javascript/testing.md +++ b/frontend/javascript/testing.md @@ -64,7 +64,8 @@ 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) | +> [!IMPORTANT] +> | **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..21e5d94 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 STRICTLY 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..8a2fabf 100644 --- a/frontend/react/performance.md +++ b/frontend/react/performance.md @@ -56,7 +56,8 @@ 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 | +> [!IMPORTANT] +> | **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..b259a19 100644 --- a/frontend/react/testing.md +++ b/frontend/react/testing.md @@ -12,7 +12,8 @@ last_updated: 2026-04-05 [⬆️ Back to Top](#) # 📖 Context & Scope -- **Primary Goal:** Enforce highly reliable, fast, and deterministic testing patterns in React. +> [!IMPORTANT] +> - **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..11779d6 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 STRICTLY not exist. ### ❌ Bad Practice ```typescript interface Config { diff --git a/frontend/typescript/objects-functions.md b/frontend/typescript/objects-functions.md index 1beff2d..013aa95 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,8 @@ 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. +> [!IMPORTANT] +> 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 +150,9 @@ 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 | +> | **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 |