[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M70J99V7Q224D1B9FNNNEA55":3,"skill-same:01M70J99V7Q224D1B9FNNNEA55":49},{"skillNo":4,"name":5,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":15,"categories":16,"keywords":17,"publishedAt":20,"linkOnly":21,"markdownContent":22,"markdownBody":23,"frontMatter":24,"refName":27,"commitSha":28,"skillDirectory":29,"forksCount":30,"repositoryHtmlUrl":31,"repositoryHomepageUrl":6,"ownerHtmlUrl":32,"ownerBlogUrl":6,"ownerDescription":33,"updatedAt":34,"install":35,"resources":48},"01M70J99V7Q224D1B9FNNNEA55","coding-standareds",null,"mdnaimul22\u002Fhuman-skills","mdnaimul22","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F64520358?v=4","01M70FH95MH2H796Q01TYSFZ03","Naimul","01M70FH96798CQR4YHA13F17GA",3,"MIT","https:\u002F\u002Fgithub.com\u002Fmdnaimul22\u002Fhuman-skills\u002Fblob\u002Fmain\u002Fskills\u002Fstorage\u002Fmy_skills\u002Fcoding-standareds\u002FSKILL.md",[],[18,19],"coding","coding standareds","2026-11-10 10:12:30",false,"---\nName: coding_standareds\nDescription: A professional and comprehensive guide transforming complex architectures into clean, maintainable systems. Focused on Clean Architecture, Unidirectional Dependency, and Type Safety.\n---\n\n# Coding Standards\n\n> *\"We build scalable infrastructure, not just scripts. So The Structure is not an optional parameter — it's the foundation.\"*\n\nYou don't like messy Spaghetti code at all. The layout of the project will be **modern schema-based, lean & flat** — centered on `src\u002F`. \n\nWhere the responsibilities of each module like core, providers, tools, helpers and config will be clearly separated through the **Single Responsibility Principle (SRP)**.\n\n> [!CAUTION]  \n> ❌ Spaghetti code, God classes, and implicit dependencies are completely prohibited.\n\n---\n\n## 1. The Core Vision (Clean Architecture)\n\n> [!NOTE]  \n> *\"Maintainable Code structure that reads like a premium framework.\"*\n\nThe code must look like it is part of a **solid, production-grade framework.**\n\n- **Naming** — The purpose can be understood simply by reading the variable\u002Ffunction\u002Fclass name.\n- **DRY** — No duplication, utilize abstraction.\n- **SOLID** — Always applicable.\n- **No dead code** — Unused imports and stale variables are strictly prohibited.\n- **Consistency** — Same pattern and same style must be maintained throughout the codebase.\n\n> [!TIP]  \n> 🎯 **Standard:** Any team member, senior or junior, should immediately understand what is happening, why it is happening, and where to extend it just by looking at the code.\n\n---\n\n## 2. Universal Dependency Flow\n\n> *\"Water never flows upward — imports always flow downward.\"*\n\n```mermaid\n---\nconfig:\n  layout: fixed\n---\nflowchart TB\n    subgraph CONFIG[\"config\u002F\"]\n        PATHS[\"paths.py\"]\n        DOTENV[\"dotenv.py\"]\n        FILES[\"files.py\"]\n        SETTINGS[\"settings.py\"]\n        CINIT[\"__init__.py\"]\n        PATHS --> DOTENV & FILES & SETTINGS\n        FILES --> SETTINGS\n        DOTENV --> SETTINGS\n        SETTINGS --> CINIT\n    end\n\n    subgraph BOOTSTRAP[\"bootstrap\"]\n        MAIN[\"main.py\\nentry point only\"]\n    end\n\n    ENV[\".env\"] -. data .-> DOTENV\n\n    CINIT --> SCHEMA[\"schema\u002F\"] & HELPERS[\"helpers\u002F\"] & CORE[\"core\u002F\"] & PROVIDERS[\"providers\u002F\"] & SERVICES[\"services\u002F\"]\n    MAIN --> CINIT & ROUTERS[\"routers\u002F\"]\n\n    SCHEMA --> CORE & PROVIDERS & SERVICES\n    HELPERS --> CORE & PROVIDERS & SERVICES\n    CORE --> SERVICES\n    PROVIDERS --> SERVICES\n    SERVICES --> ROUTERS\n\n    UI[\"UI\"] -- HTTP Request --> ROUTERS\n    ROUTERS -- HTTP Response --> UI\n```\n\n**Import Permission Table:**\n\n| Module | Can Import From | Blind To |\n|:---|:---|:---|\n| `config\u002F` | `.env` (data only) | everything |\n| `schema\u002F` | `config\u002F` | `core`, `providers`, `services`, `routers` |\n| `helpers\u002F` | `config\u002F` | `core`, `providers`, `services`, `routers` |\n| `core\u002F` | `config\u002F`, `schema\u002F`, `helpers\u002F` | `providers\u002F`, `services\u002F`, `routers\u002F` |\n| `providers\u002F` | `config\u002F`, `schema\u002F`, `helpers\u002F` | `core\u002F`, `services\u002F`, `routers\u002F` |\n| `services\u002F` | `config\u002F`, `schema\u002F`, `helpers\u002F`, `core\u002F`, `providers\u002F` | `routers\u002F` |\n| `routers\u002F` | `services\u002F`, `schema\u002F` | `core\u002F`, `providers\u002F`, `helpers\u002F` |\n| `main.py` | `config\u002F`, `routers\u002F` | internal business logic |\n\n---\n\n## 3. The Structural Blueprint (Dependency & Directory Rules)\n\n### 3.1 Dependency Rule\n> *\"Imports flow in one direction\"*\n\nThe core rule of clean architecture is that imports should always be unidirectional to prevent circular dependencies. Correctly executing a Strict Dependency Rule exponentially increases the Scalability and Maintainability of a project.\n\n#### 1. Top-level Isolation\nEach folder in the project, such as `config`, `schema`, `api`, `browser`, `session`, `providers`, `tools`, `services`, will act as an independent module. None shall interfere with the internal affairs of another.\n\n#### 2. Layer Trust \u002F Unidirectional Flow\n\n**The Core Truth:**\n- `root\u002F.env` is the Single Source of Truth for project environment variables. It manipulates `src\u002Fconfig\u002Fsettings.py`. For example: `LOG_DIR=logs`, `JINA_API_KEY=abcd`\n- `src\u002Fconfig\u002F`:\n  - `src\u002Fconfig\u002Fsettings.py` is the gearbox of the entire project. The environment driver controls the project through this gearbox.  \n    *(For example: `LOG_DIR: str = Field(default=\"logs\", validation_alias=\"LOG_DIR\")`, `@property \\n def LOG_DIR(self) -> Path: \\n return self._resolve_path(self.LOG_DIR)`)*\n  - `src\u002Fconfig\u002Fdotenv.py`\n  - `src\u002Fconfig\u002F__init__.py`\n- `src\u002Fschema\u002F`: This directory holds the absolute truth for **Pydantic modeling** standards (`models.py`). It does not import or call any local modules; rather, the entire project depends on it.\n\n**Dependency Privacy:**\n- `src\u002F{module}\u002Fhelpers\u002F`: Each module can have its own `helpers\u002F` folder. These helpers are entirely private. Meaning, one module like `src\u002Fapi\u002F*` or `src\u002Fapi\u002F__init__.py` will never import or call the private helpers of another module like `src\u002F{module}\u002Fhelpers\u002F*`. These `helpers` can only be called by their respective `src\u002F{module}\u002F*`.\n- `src\u002Fhelpers\u002F`: If any global helper logic (e.g., date formatting, logging) is needed across multiple modules, it belongs in the project root `src\u002Fhelpers\u002F`. Everyone is allowed to import or call these globally.\n\n**Core Infrastructures:**\n- **`src\u002Fcore\u002F`**: Knows `src\u002Fschema\u002F__init__.py`, `src\u002Fconfig\u002F__init__.py`, and `src\u002Fhelpers\u002F`.\n- **`src\u002Fproviders\u002F`**: Knows `src\u002Fschema\u002F__init__.py`, `src\u002Fconfig\u002F__init__.py`, and `src\u002Fhelpers\u002F`. Peer of `core\u002F` — they are blind to each other.\n- **`src\u002Fservices\u002F`**: The **fan-in point**. Knows `src\u002Fcore\u002F__init__.py`, `src\u002Fproviders\u002F__init__.py`, `src\u002Fschema\u002F__init__.py`, `src\u002Fconfig\u002F__init__.py`, and `src\u002Fhelpers\u002F`. This is where `core\u002F` and `providers\u002F` converge.\n- **`src\u002Frouters\u002F`**: Only knows `src\u002Fservices\u002F__init__.py` and `src\u002Fschema\u002F__init__.py`. No business logic — HTTP interface only.\n- **`src\u002Fapi\u002Ffrontend\u002F`**: Merely used to represent `src\u002Fservices\u002F*` to the frontend.\n- **`src\u002Ftools\u002F`**: If tools are utilized to build a Model Context Server or Function Calling Interface for the agent, they act like a CLI interface that calls `src\u002Fservices\u002F*`. They take arguments as input and return structured outputs.\n\n### 3.2 Directory Structure Rules\n\n**Rule 1 — Directory Name = Its Responsibility**\nA directory's name strictly defines its single responsibility.\nAll scripts inside that directory must cover the sub-responsibilities of that exact context.\n\n```bash\nproviders\u002F    ← AI\u002Fexternal service integrations ONLY\ncore\u002F         ← Business logic ONLY\nhelpers\u002F      ← Global utilities that assist the entire project ONLY\nconfig\u002F       ← All configuration ONLY\ntools\u002F        ← Reusable standalone operations ONLY\n```\n\n**Rule 2 — `\u002Fconfig\u002F` is the Single Source of Truth**\nIf there are hardcoded or scattered parameters anywhere in the project, they must be migrated to `\u002Fconfig\u002F`. The `__init__.py` file aggregates and exposes all configs.\n\n```python\n# ❌ Avoid\nMODEL = \"gpt-4o\"  # hardcoded inside core\u002Fagent.py\n\n# ✅ Prefer\nclass LLMConfig(BaseSettings):\n    model: str = \"gpt-4o\"\n```\n\n**Rule 3 — Sub-Responsibility Allowed, Cross-Responsibility Forbidden**\n\n```bash\nproviders\u002F\n├── openai.py        ✅ Sub-responsibility of \"providers\"\n├── anthropic.py     ✅ Sub-responsibility of \"providers\"\n└── formatter.py     ❌ This is the job of helpers\u002F\n```\n\n**Cross-Responsibility Violation — Detection & Fix:**\n\n```bash\n# ❌ Violation\nhelpers\u002F\n└── gemini_caller.py     ← AI Provider call — what is this doing in helpers\u002F?\n\n# ✅ After fix\nproviders\u002F\n└── gemini.py            ← Migrated to the correct location\n```\n\n---\n\n## 4. Coding Guidelines (Safety, Performance, Security)\n\n### 4.1 Type Safety\n\n> [!WARNING]  \n> **Ambiguity kills maintainability.**\n\nAlways utilize **Pydantic models** and Python **Type Hints**.\nThe code must be completely **`mypy` \u002F `pyright` error-free**.\n\n```python\n# ❌ Avoid\ndata: dict = {}\nvalue: Any = get_value()\n\n# ✅ Prefer\ndata: UserConfig = UserConfig(...)\nvalue: ResponsePayload = get_value()\n```\n\n> If using raw `dict` or `Any` is unavoidable, there must be a clear and explicit justification.\n\n### 4.2 Boundary Defense & Null Elimination (The Tony Hoare Rule)\n\n> *\"I call it my billion-dollar mistake. It was the invention of the null reference in 1965.\" — Sir Tony Hoare*  \n> **\"Don't check for None repeatedly — eliminate None at the boundary.\"**\n\nNever allow defensive, repetitive `None` checks to pollute core business logic.\n\n- **Sanitize at the Perimeter (Null Object Pattern):** When receiving optional or external data at module boundaries, resolve them immediately to a safe, typed default (e.g., `canvas = template.canvas if (template and template.canvas) else CanvasConfig()`).\n- **Guaranteed Invariants Inside the Core:** Once past the entry boundary, assume entities are valid, non-null objects. Core logic should never fear `None`.\n- **Prohibited:** Never scatter `obj.field if obj else default` across downstream calculations or rendering passes.\n\n```python\n# ❌ Avoid (Noisy defensive checks polluting business logic)\ndef process(context):\n    mode = context.canvas.mode if context.canvas else \"blur\"\n    intensity = context.canvas.blur_intensity if context.canvas else 30\n    darken = context.canvas.darken_alpha if context.canvas else 0.25\n\n# ✅ Prefer (Tony Hoare Boundary Defense \u002F Null Object Pattern)\ndef process(context):\n    # Eliminate None once at the entry boundary:\n    canvas = context.template.canvas if (context.template and context.template.canvas) else CanvasConfig()\n\n    # Pure business logic — zero null-checking noise:\n    mode = canvas.mode\n    intensity = canvas.blur_intensity\n    darken = canvas.darken_alpha\n```\n\n### 4.3 Performance & Determinism\n> *\"Fast by design, not by accident.\"*\n\nThe system design will be **ultra-fast** and must follow an **extensible pattern** in all scenarios.\n\n- [ ] Adding a new provider requires zero modifications to the core.\n- [ ] Configuration-driven behavior — hardcoded values are prohibited.\n- [ ] Async-first — always use `async\u002Fawait` for I\u002FO bound operations.\n- [ ] Implement lazy loading wherever applicable.\n\n### 4.4 Robustness\n> *\"New features must land on solid ground.\"*\n\nAdding a new feature = **existing code remains untouched**, only new modules\u002Flayers are extended.\n\n> `Schema First → Clean Interfaces → Stable Core → Safe Extensions`\n\n**Every component must possess:**\n- [ ] Structured error handling (`try\u002Fexcept` with typed exceptions).\n- [ ] Meaningful logging — `print()` is prohibited. Consolidate logs by layer (e.g., `service.log`, `router.log`) instead of per-script.\n- [ ] Graceful degradation — a single failure will not bring down the entire system.\n\n### 4.5 Security-Safety Practices\n> *\"Security is a first-class citizen, not an afterthought.\"*  \n> **With Comprehensive test coverage that is maintained continuously**\n\n| Risk | Mitigation Strategy |\n| :--- | :--- |\n| **Injection Attacks (SQL\u002FCommand\u002FShell)** | Never concatenate user input directly into executable strings. Always use Parameterized queries, ORM, or Safe execution APIs. |\n| **Path Traversal** | When accessing the file system, sanitize any user-provided path inputs and strictly enforce sandbox boundaries to block access outside permitted directories. |\n| **Secret Leakage** | Never hardcode API Keys or Credentials in the source code. Always use Environment Variables (`.env`) or a Secret Manager. |\n| **Rate Limiting & Abuse** | Enforce request rate sizing limit restrictions and payload thresholds on all public\u002Fexternal APIs. |\n| **Failover & Stability** | Implement Error Retry Logic with Exponential Backoff to prevent system crashes triggered by network failures during third-party or external API calls. |\n\n---\n\n## 5. Code Craftsmanship & Maintenance\n\n### 5.1 Advanced Refactoring & Code Evolution\n> *\"Refactoring is a deliberate process, not a quick fix.\"*\n\n**Zero Behavior Changes Verified** — The primary goal of refactoring is to significantly reduce complexity and consistently ensure safety, but the behavior of existing code must never be broken under any circumstances.\n\n#### Before You Begin\nBefore starting, you must thoroughly understand the dependency map (Module boundaries, Layer extraction) of the entire codebase. Modifying any file without comprehending it is strictly prohibited.\n\n#### The Master Refactoring Strategy\n\n> [!IMPORTANT]  \n> **Method Extraction & Clean-up:** Long method decomposition • Complex conditional extraction • Loop body extraction • Duplicate code consolidation • Guard clause introduction • Command query separation.\n\n- **Design Pattern Application:** Apply `Strategy`, `Factory`, `Observer`, or `Decorator` patterns. Eliminate hardcoded if-else or switch\u002Fcase logic using *Replace Conditional with Polymorphism* or *Replace Type Code with Subclasses*.\n- **API & Database Optimization:** \n  - **API:** Ensure Endpoint consolidation, Error handling standardization, Versioning strategy, and firmly maintain backward compatibility.\n  - **Database:** Boost performance using Query simplification, Schema normalization, Index optimization, and Caching strategies (Lazy evaluation).\n- **Architectural Refactoring:** Break tight-coupling using Interface segregation and Dependency inversion (*Replace Inheritance with Delegation*, *Extract Interface*). Consider separate Service extraction or Event-driven refactoring if required.\n- **Safety First:** At the end of the refactoring process, validate utilizing Regression detection and Coverage analysis to ensure that the initial functionality works exactly as prior.\n\n---\n\n## 6. Verification & Testing\n\nTesting is mandatory not just for finding bugs in the code, but for keeping the codebase production-ready and future-proof. The following verification strategies must be applied throughout the project lifecycle:\n\n- **Golden Master \u002F Approval Testing:** When refactoring legacy code or validating complex outputs, save the current behavior as a \"Golden Record\". Ensure that the new output maps exactly identically post-refactoring.\n- **Mutation Testing:** To verify the actual robustness of the unit tests you have written, introduce deliberate bugs (Mutants) into the main code and see if the tests fail. 100% coverage does not equate to safety; having robust assertions is far more critical.\n- **Performance Testing:** Validate whether the system design is genuinely ultra-fast. Measure if I\u002FO bound operations during loads are triggering blocking issues.\n- **Characterization Tests:** Execute these tests to comprehend the undocumented behaviors of any library or third-party API so your system does not break if the API updates in the future.\n- **Integration Validation:** Validate that end-to-end data flow operates perfectly when different modules — specifically the `services\u002F`, `providers\u002F`, and `database` layers — interact simultaneously.\n- **Memory Optimization & Resource Pooling:** Ensure proper connection pooling for database or external API calls. Maintain resource cleanup (e.g., using `finally` blocks or `async with` context managers) to prevent memory leaks and slower responses.\n\n---\n> [!NOTE]  \n> - **For project tree examples and relationships, follow:** `.agents\u002Frules\u002Fproject-tree-example.md`\n> - **For project configuration example follow:** `.agents\u002Frules\u002Fproject-config-example.md`","# Coding Standards\n\n> *\"We build scalable infrastructure, not just scripts. So The Structure is not an optional parameter — it's the foundation.\"*\n\nYou don't like messy Spaghetti code at all. The layout of the project will be **modern schema-based, lean & flat** — centered on `src\u002F`. \n\nWhere the responsibilities of each module like core, providers, tools, helpers and config will be clearly separated through the **Single Responsibility Principle (SRP)**.\n\n> [!CAUTION]  \n> ❌ Spaghetti code, God classes, and implicit dependencies are completely prohibited.\n\n---\n\n## 1. The Core Vision (Clean Architecture)\n\n> [!NOTE]  \n> *\"Maintainable Code structure that reads like a premium framework.\"*\n\nThe code must look like it is part of a **solid, production-grade framework.**\n\n- **Naming** — The purpose can be understood simply by reading the variable\u002Ffunction\u002Fclass name.\n- **DRY** — No duplication, utilize abstraction.\n- **SOLID** — Always applicable.\n- **No dead code** — Unused imports and stale variables are strictly prohibited.\n- **Consistency** — Same pattern and same style must be maintained throughout the codebase.\n\n> [!TIP]  \n> 🎯 **Standard:** Any team member, senior or junior, should immediately understand what is happening, why it is happening, and where to extend it just by looking at the code.\n\n---\n\n## 2. Universal Dependency Flow\n\n> *\"Water never flows upward — imports always flow downward.\"*\n\n```mermaid\n---\nconfig:\n  layout: fixed\n---\nflowchart TB\n    subgraph CONFIG[\"config\u002F\"]\n        PATHS[\"paths.py\"]\n        DOTENV[\"dotenv.py\"]\n        FILES[\"files.py\"]\n        SETTINGS[\"settings.py\"]\n        CINIT[\"__init__.py\"]\n        PATHS --> DOTENV & FILES & SETTINGS\n        FILES --> SETTINGS\n        DOTENV --> SETTINGS\n        SETTINGS --> CINIT\n    end\n\n    subgraph BOOTSTRAP[\"bootstrap\"]\n        MAIN[\"main.py\\nentry point only\"]\n    end\n\n    ENV[\".env\"] -. data .-> DOTENV\n\n    CINIT --> SCHEMA[\"schema\u002F\"] & HELPERS[\"helpers\u002F\"] & CORE[\"core\u002F\"] & PROVIDERS[\"providers\u002F\"] & SERVICES[\"services\u002F\"]\n    MAIN --> CINIT & ROUTERS[\"routers\u002F\"]\n\n    SCHEMA --> CORE & PROVIDERS & SERVICES\n    HELPERS --> CORE & PROVIDERS & SERVICES\n    CORE --> SERVICES\n    PROVIDERS --> SERVICES\n    SERVICES --> ROUTERS\n\n    UI[\"UI\"] -- HTTP Request --> ROUTERS\n    ROUTERS -- HTTP Response --> UI\n```\n\n**Import Permission Table:**\n\n| Module | Can Import From | Blind To |\n|:---|:---|:---|\n| `config\u002F` | `.env` (data only) | everything |\n| `schema\u002F` | `config\u002F` | `core`, `providers`, `services`, `routers` |\n| `helpers\u002F` | `config\u002F` | `core`, `providers`, `services`, `routers` |\n| `core\u002F` | `config\u002F`, `schema\u002F`, `helpers\u002F` | `providers\u002F`, `services\u002F`, `routers\u002F` |\n| `providers\u002F` | `config\u002F`, `schema\u002F`, `helpers\u002F` | `core\u002F`, `services\u002F`, `routers\u002F` |\n| `services\u002F` | `config\u002F`, `schema\u002F`, `helpers\u002F`, `core\u002F`, `providers\u002F` | `routers\u002F` |\n| `routers\u002F` | `services\u002F`, `schema\u002F` | `core\u002F`, `providers\u002F`, `helpers\u002F` |\n| `main.py` | `config\u002F`, `routers\u002F` | internal business logic |\n\n---\n\n## 3. The Structural Blueprint (Dependency & Directory Rules)\n\n### 3.1 Dependency Rule\n> *\"Imports flow in one direction\"*\n\nThe core rule of clean architecture is that imports should always be unidirectional to prevent circular dependencies. Correctly executing a Strict Dependency Rule exponentially increases the Scalability and Maintainability of a project.\n\n#### 1. Top-level Isolation\nEach folder in the project, such as `config`, `schema`, `api`, `browser`, `session`, `providers`, `tools`, `services`, will act as an independent module. None shall interfere with the internal affairs of another.\n\n#### 2. Layer Trust \u002F Unidirectional Flow\n\n**The Core Truth:**\n- `root\u002F.env` is the Single Source of Truth for project environment variables. It manipulates `src\u002Fconfig\u002Fsettings.py`. For example: `LOG_DIR=logs`, `JINA_API_KEY=abcd`\n- `src\u002Fconfig\u002F`:\n  - `src\u002Fconfig\u002Fsettings.py` is the gearbox of the entire project. The environment driver controls the project through this gearbox.  \n    *(For example: `LOG_DIR: str = Field(default=\"logs\", validation_alias=\"LOG_DIR\")`, `@property \\n def LOG_DIR(self) -> Path: \\n return self._resolve_path(self.LOG_DIR)`)*\n  - `src\u002Fconfig\u002Fdotenv.py`\n  - `src\u002Fconfig\u002F__init__.py`\n- `src\u002Fschema\u002F`: This directory holds the absolute truth for **Pydantic modeling** standards (`models.py`). It does not import or call any local modules; rather, the entire project depends on it.\n\n**Dependency Privacy:**\n- `src\u002F{module}\u002Fhelpers\u002F`: Each module can have its own `helpers\u002F` folder. These helpers are entirely private. Meaning, one module like `src\u002Fapi\u002F*` or `src\u002Fapi\u002F__init__.py` will never import or call the private helpers of another module like `src\u002F{module}\u002Fhelpers\u002F*`. These `helpers` can only be called by their respective `src\u002F{module}\u002F*`.\n- `src\u002Fhelpers\u002F`: If any global helper logic (e.g., date formatting, logging) is needed across multiple modules, it belongs in the project root `src\u002Fhelpers\u002F`. Everyone is allowed to import or call these globally.\n\n**Core Infrastructures:**\n- **`src\u002Fcore\u002F`**: Knows `src\u002Fschema\u002F__init__.py`, `src\u002Fconfig\u002F__init__.py`, and `src\u002Fhelpers\u002F`.\n- **`src\u002Fproviders\u002F`**: Knows `src\u002Fschema\u002F__init__.py`, `src\u002Fconfig\u002F__init__.py`, and `src\u002Fhelpers\u002F`. Peer of `core\u002F` — they are blind to each other.\n- **`src\u002Fservices\u002F`**: The **fan-in point**. Knows `src\u002Fcore\u002F__init__.py`, `src\u002Fproviders\u002F__init__.py`, `src\u002Fschema\u002F__init__.py`, `src\u002Fconfig\u002F__init__.py`, and `src\u002Fhelpers\u002F`. This is where `core\u002F` and `providers\u002F` converge.\n- **`src\u002Frouters\u002F`**: Only knows `src\u002Fservices\u002F__init__.py` and `src\u002Fschema\u002F__init__.py`. No business logic — HTTP interface only.\n- **`src\u002Fapi\u002Ffrontend\u002F`**: Merely used to represent `src\u002Fservices\u002F*` to the frontend.\n- **`src\u002Ftools\u002F`**: If tools are utilized to build a Model Context Server or Function Calling Interface for the agent, they act like a CLI interface that calls `src\u002Fservices\u002F*`. They take arguments as input and return structured outputs.\n\n### 3.2 Directory Structure Rules\n\n**Rule 1 — Directory Name = Its Responsibility**\nA directory's name strictly defines its single responsibility.\nAll scripts inside that directory must cover the sub-responsibilities of that exact context.\n\n```bash\nproviders\u002F    ← AI\u002Fexternal service integrations ONLY\ncore\u002F         ← Business logic ONLY\nhelpers\u002F      ← Global utilities that assist the entire project ONLY\nconfig\u002F       ← All configuration ONLY\ntools\u002F        ← Reusable standalone operations ONLY\n```\n\n**Rule 2 — `\u002Fconfig\u002F` is the Single Source of Truth**\nIf there are hardcoded or scattered parameters anywhere in the project, they must be migrated to `\u002Fconfig\u002F`. The `__init__.py` file aggregates and exposes all configs.\n\n```python\n# ❌ Avoid\nMODEL = \"gpt-4o\"  # hardcoded inside core\u002Fagent.py\n\n# ✅ Prefer\nclass LLMConfig(BaseSettings):\n    model: str = \"gpt-4o\"\n```\n\n**Rule 3 — Sub-Responsibility Allowed, Cross-Responsibility Forbidden**\n\n```bash\nproviders\u002F\n├── openai.py        ✅ Sub-responsibility of \"providers\"\n├── anthropic.py     ✅ Sub-responsibility of \"providers\"\n└── formatter.py     ❌ This is the job of helpers\u002F\n```\n\n**Cross-Responsibility Violation — Detection & Fix:**\n\n```bash\n# ❌ Violation\nhelpers\u002F\n└── gemini_caller.py     ← AI Provider call — what is this doing in helpers\u002F?\n\n# ✅ After fix\nproviders\u002F\n└── gemini.py            ← Migrated to the correct location\n```\n\n---\n\n## 4. Coding Guidelines (Safety, Performance, Security)\n\n### 4.1 Type Safety\n\n> [!WARNING]  \n> **Ambiguity kills maintainability.**\n\nAlways utilize **Pydantic models** and Python **Type Hints**.\nThe code must be completely **`mypy` \u002F `pyright` error-free**.\n\n```python\n# ❌ Avoid\ndata: dict = {}\nvalue: Any = get_value()\n\n# ✅ Prefer\ndata: UserConfig = UserConfig(...)\nvalue: ResponsePayload = get_value()\n```\n\n> If using raw `dict` or `Any` is unavoidable, there must be a clear and explicit justification.\n\n### 4.2 Boundary Defense & Null Elimination (The Tony Hoare Rule)\n\n> *\"I call it my billion-dollar mistake. It was the invention of the null reference in 1965.\" — Sir Tony Hoare*  \n> **\"Don't check for None repeatedly — eliminate None at the boundary.\"**\n\nNever allow defensive, repetitive `None` checks to pollute core business logic.\n\n- **Sanitize at the Perimeter (Null Object Pattern):** When receiving optional or external data at module boundaries, resolve them immediately to a safe, typed default (e.g., `canvas = template.canvas if (template and template.canvas) else CanvasConfig()`).\n- **Guaranteed Invariants Inside the Core:** Once past the entry boundary, assume entities are valid, non-null objects. Core logic should never fear `None`.\n- **Prohibited:** Never scatter `obj.field if obj else default` across downstream calculations or rendering passes.\n\n```python\n# ❌ Avoid (Noisy defensive checks polluting business logic)\ndef process(context):\n    mode = context.canvas.mode if context.canvas else \"blur\"\n    intensity = context.canvas.blur_intensity if context.canvas else 30\n    darken = context.canvas.darken_alpha if context.canvas else 0.25\n\n# ✅ Prefer (Tony Hoare Boundary Defense \u002F Null Object Pattern)\ndef process(context):\n    # Eliminate None once at the entry boundary:\n    canvas = context.template.canvas if (context.template and context.template.canvas) else CanvasConfig()\n\n    # Pure business logic — zero null-checking noise:\n    mode = canvas.mode\n    intensity = canvas.blur_intensity\n    darken = canvas.darken_alpha\n```\n\n### 4.3 Performance & Determinism\n> *\"Fast by design, not by accident.\"*\n\nThe system design will be **ultra-fast** and must follow an **extensible pattern** in all scenarios.\n\n- [ ] Adding a new provider requires zero modifications to the core.\n- [ ] Configuration-driven behavior — hardcoded values are prohibited.\n- [ ] Async-first — always use `async\u002Fawait` for I\u002FO bound operations.\n- [ ] Implement lazy loading wherever applicable.\n\n### 4.4 Robustness\n> *\"New features must land on solid ground.\"*\n\nAdding a new feature = **existing code remains untouched**, only new modules\u002Flayers are extended.\n\n> `Schema First → Clean Interfaces → Stable Core → Safe Extensions`\n\n**Every component must possess:**\n- [ ] Structured error handling (`try\u002Fexcept` with typed exceptions).\n- [ ] Meaningful logging — `print()` is prohibited. Consolidate logs by layer (e.g., `service.log`, `router.log`) instead of per-script.\n- [ ] Graceful degradation — a single failure will not bring down the entire system.\n\n### 4.5 Security-Safety Practices\n> *\"Security is a first-class citizen, not an afterthought.\"*  \n> **With Comprehensive test coverage that is maintained continuously**\n\n| Risk | Mitigation Strategy |\n| :--- | :--- |\n| **Injection Attacks (SQL\u002FCommand\u002FShell)** | Never concatenate user input directly into executable strings. Always use Parameterized queries, ORM, or Safe execution APIs. |\n| **Path Traversal** | When accessing the file system, sanitize any user-provided path inputs and strictly enforce sandbox boundaries to block access outside permitted directories. |\n| **Secret Leakage** | Never hardcode API Keys or Credentials in the source code. Always use Environment Variables (`.env`) or a Secret Manager. |\n| **Rate Limiting & Abuse** | Enforce request rate sizing limit restrictions and payload thresholds on all public\u002Fexternal APIs. |\n| **Failover & Stability** | Implement Error Retry Logic with Exponential Backoff to prevent system crashes triggered by network failures during third-party or external API calls. |\n\n---\n\n## 5. Code Craftsmanship & Maintenance\n\n### 5.1 Advanced Refactoring & Code Evolution\n> *\"Refactoring is a deliberate process, not a quick fix.\"*\n\n**Zero Behavior Changes Verified** — The primary goal of refactoring is to significantly reduce complexity and consistently ensure safety, but the behavior of existing code must never be broken under any circumstances.\n\n#### Before You Begin\nBefore starting, you must thoroughly understand the dependency map (Module boundaries, Layer extraction) of the entire codebase. Modifying any file without comprehending it is strictly prohibited.\n\n#### The Master Refactoring Strategy\n\n> [!IMPORTANT]  \n> **Method Extraction & Clean-up:** Long method decomposition • Complex conditional extraction • Loop body extraction • Duplicate code consolidation • Guard clause introduction • Command query separation.\n\n- **Design Pattern Application:** Apply `Strategy`, `Factory`, `Observer`, or `Decorator` patterns. Eliminate hardcoded if-else or switch\u002Fcase logic using *Replace Conditional with Polymorphism* or *Replace Type Code with Subclasses*.\n- **API & Database Optimization:** \n  - **API:** Ensure Endpoint consolidation, Error handling standardization, Versioning strategy, and firmly maintain backward compatibility.\n  - **Database:** Boost performance using Query simplification, Schema normalization, Index optimization, and Caching strategies (Lazy evaluation).\n- **Architectural Refactoring:** Break tight-coupling using Interface segregation and Dependency inversion (*Replace Inheritance with Delegation*, *Extract Interface*). Consider separate Service extraction or Event-driven refactoring if required.\n- **Safety First:** At the end of the refactoring process, validate utilizing Regression detection and Coverage analysis to ensure that the initial functionality works exactly as prior.\n\n---\n\n## 6. Verification & Testing\n\nTesting is mandatory not just for finding bugs in the code, but for keeping the codebase production-ready and future-proof. The following verification strategies must be applied throughout the project lifecycle:\n\n- **Golden Master \u002F Approval Testing:** When refactoring legacy code or validating complex outputs, save the current behavior as a \"Golden Record\". Ensure that the new output maps exactly identically post-refactoring.\n- **Mutation Testing:** To verify the actual robustness of the unit tests you have written, introduce deliberate bugs (Mutants) into the main code and see if the tests fail. 100% coverage does not equate to safety; having robust assertions is far more critical.\n- **Performance Testing:** Validate whether the system design is genuinely ultra-fast. Measure if I\u002FO bound operations during loads are triggering blocking issues.\n- **Characterization Tests:** Execute these tests to comprehend the undocumented behaviors of any library or third-party API so your system does not break if the API updates in the future.\n- **Integration Validation:** Validate that end-to-end data flow operates perfectly when different modules — specifically the `services\u002F`, `providers\u002F`, and `database` layers — interact simultaneously.\n- **Memory Optimization & Resource Pooling:** Ensure proper connection pooling for database or external API calls. Maintain resource cleanup (e.g., using `finally` blocks or `async with` context managers) to prevent memory leaks and slower responses.\n\n---\n> [!NOTE]  \n> - **For project tree examples and relationships, follow:** `.agents\u002Frules\u002Fproject-tree-example.md`\n> - **For project configuration example follow:** `.agents\u002Frules\u002Fproject-config-example.md`",{"Name":25,"Description":26},"coding_standareds","A professional and comprehensive guide transforming complex architectures into clean, maintainable systems. Focused on Clean Architecture, Unidirectional Dependency, and Type Safety.","main","74715deacdc69119d739f38916f8ee4f0f979ebf","skills\u002Fstorage\u002Fmy_skills\u002Fcoding-standareds",0,"https:\u002F\u002Fgithub.com\u002Fmdnaimul22\u002Fhuman-skills","https:\u002F\u002Fgithub.com\u002Fmdnaimul22","AI Agents Workflows Automation | Specializing in Python, FastAPI, MCP Agents & Custom ERP.","2026-11-11 21:16:57",{"source":7,"skillName":5,"commands":36,"prompt":46,"zipAvailable":47},[37,40,43],{"tool":38,"command":39},"npx","npx skills add mdnaimul22\u002Fhuman-skills --skill coding-standareds",{"tool":41,"command":42},"bunx","bunx skills add mdnaimul22\u002Fhuman-skills --skill coding-standareds",{"tool":44,"command":45},"pnpm","pnpm dlx skills add mdnaimul22\u002Fhuman-skills --skill coding-standareds","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fmdnaimul22\u002Fhuman-skills\u002Fblob\u002Fmain\u002Fskills\u002Fstorage\u002Fmy_skills\u002Fcoding-standareds\u002FSKILL.md",true,[],[50,58,66,73,80,87],{"skillNo":51,"name":52,"nameZh":6,"description":53,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":54,"categories":55,"keywords":56,"publishedAt":57},"01M767791C1KRP2ZRW2Z73VZ5Q","system-lifecycle-designer","Universal architectural methodology for designing granular, atomic, and sub-atomic lifecycles and end-to-end workflows for single functionality integrations across any domain (daemons, batch jobs, request transactions, resource pools). Provides patterns for deterministic identity, pre-commit validation, differential reconciliation, sticky leasing, state machines, transactional persistence, and closed-loop feedback.","https:\u002F\u002Fgithub.com\u002Fmdnaimul22\u002Fhuman-skills\u002Fblob\u002Fmain\u002Fskills\u002Fstorage\u002Fmy_skills\u002Fsystem-lifecycle-designer\u002FSKILL.md",[],[],"2026-11-12 13:55:43",{"skillNo":59,"name":60,"nameZh":6,"description":61,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":62,"categories":63,"keywords":64,"publishedAt":65},"01M748ABPN5F1FANHH6HKZQMXT","style-sampling","Make a new episode in a proven video style - Collage Explainer, Finance Explainer, Animated Science Explainer, 3D Brand Explainer, 3D True Crime - on the person's topic. Use for \"an episode of\", \"in the style of\", \"sample this style\", 「用这个风格做一集」. One video to copy is reverse-any-video.","https:\u002F\u002Fgithub.com\u002Fmdnaimul22\u002Fhuman-skills\u002Fblob\u002Fmain\u002Fskills\u002Fstorage\u002Fheygen-com_hyperframes\u002Fstyle-sampling\u002FSKILL.md",[],[],"2026-11-11 15:11:14",{"skillNo":67,"name":68,"nameZh":6,"description":69,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":70,"categories":71,"keywords":72,"publishedAt":65},"01M748A59V04PKW4HA0XQ81FGP","reverse-any-video","Rebuild any video file as an editable HyperFrames project - motion graphics, talking heads, live action or AI-generated footage - checked against the original frame by frame. Use to reverse, recreate, remake, replicate or copy a video, or 「复刻这个视频」「照着这个视频做一个」.","https:\u002F\u002Fgithub.com\u002Fmdnaimul22\u002Fhuman-skills\u002Fblob\u002Fmain\u002Fskills\u002Fstorage\u002Fheygen-com_hyperframes\u002Freverse-any-video\u002FSKILL.md",[],[],{"skillNo":74,"name":75,"nameZh":6,"description":76,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":77,"categories":78,"keywords":79,"publishedAt":65},"01M7487T50P55CSXMWXZ0G9KRG","typescript-patterns","TypeScript patterns for strict, type-safe, maintainable code in modern TypeScript and JavaScript applications. Covers strict compiler configuration, type design, narrowing, discriminated unions, generics, async and error handling, module boundaries, dependency hygiene, and type-level testing. Use when writing or reviewing TypeScript or JavaScript code.","https:\u002F\u002Fgithub.com\u002Fmdnaimul22\u002Fhuman-skills\u002Fblob\u002Fmain\u002Fskills\u002Fstorage\u002Faffaan-m_ECC\u002Ftypescript-patterns\u002FSKILL.md",[],[],{"skillNo":81,"name":82,"nameZh":6,"description":83,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":84,"categories":85,"keywords":86,"publishedAt":65},"01M7487ERZRGPC5NJ75077Y238","test-collaboration","Inventory and govern a project's test assets. Connect requirements, business rules, risks, bugs, and cross-boundary contracts to stable TEST-IDs and executable evidence in the repository's existing test registry or TESTS.md. Use for test inventory, test gap analysis, unit\u002Fintegration\u002Fcontract\u002FE2E\u002Fsmoke classification, bug-to-test regression protection, consumer\u002Fprovider contract testing, test-necessity review, and pre-delivery evidence review.","https:\u002F\u002Fgithub.com\u002Fmdnaimul22\u002Fhuman-skills\u002Fblob\u002Fmain\u002Fskills\u002Fstorage\u002Faffaan-m_ECC\u002Ftest-collaboration\u002FSKILL.md",[],[],{"skillNo":88,"name":89,"nameZh":6,"description":90,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":91,"categories":92,"keywords":93,"publishedAt":65},"01M748721J3GKR2WS6K0QWFC35","story-lifecycle","Manage a file-based epic → story → sprint development loop without requiring an external project management tool. Creates and tracks epics, breaks them into user stories, assigns them to sprints, and drives implementation story by story. Use when starting a new feature initiative or when the team has no Jira\u002FLinear\u002FTaiga but needs structured delivery tracking.","https:\u002F\u002Fgithub.com\u002Fmdnaimul22\u002Fhuman-skills\u002Fblob\u002Fmain\u002Fskills\u002Fstorage\u002Faffaan-m_ECC\u002Fstory-lifecycle\u002FSKILL.md",[],[]]