AGENT SKILL

coding-standareds

暂无简介

License 许可
MIT
最近更新
2026-11-11
Stars
★ 3
Forks
0

01 前言 Front Matter

Name
coding_standareds
Description
A professional and comprehensive guide transforming complex architectures into clean, maintainable systems. Focused on Clean Architecture, Unidirectional Dependency, and Type Safety.

03 SKILL.md 正文

Coding Standards

"We build scalable infrastructure, not just scripts. So The Structure is not an optional parameter — it's the foundation."

You don't like messy Spaghetti code at all. The layout of the project will be modern schema-based, lean & flat — centered on src/.

Where the responsibilities of each module like core, providers, tools, helpers and config will be clearly separated through the Single Responsibility Principle (SRP).

[!CAUTION]
❌ Spaghetti code, God classes, and implicit dependencies are completely prohibited.


1. The Core Vision (Clean Architecture)

[!NOTE]
"Maintainable Code structure that reads like a premium framework."

The code must look like it is part of a solid, production-grade framework.

  • Naming — The purpose can be understood simply by reading the variable/function/class name.
  • DRY — No duplication, utilize abstraction.
  • SOLID — Always applicable.
  • No dead code — Unused imports and stale variables are strictly prohibited.
  • Consistency — Same pattern and same style must be maintained throughout the codebase.

[!TIP]
🎯 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.


2. Universal Dependency Flow

"Water never flows upward — imports always flow downward."

---
config:
  layout: fixed
---
flowchart TB
    subgraph CONFIG["config/"]
        PATHS["paths.py"]
        DOTENV["dotenv.py"]
        FILES["files.py"]
        SETTINGS["settings.py"]
        CINIT["__init__.py"]
        PATHS --> DOTENV & FILES & SETTINGS
        FILES --> SETTINGS
        DOTENV --> SETTINGS
        SETTINGS --> CINIT
    end

    subgraph BOOTSTRAP["bootstrap"]
        MAIN["main.py\nentry point only"]
    end

    ENV[".env"] -. data .-> DOTENV

    CINIT --> SCHEMA["schema/"] & HELPERS["helpers/"] & CORE["core/"] & PROVIDERS["providers/"] & SERVICES["services/"]
    MAIN --> CINIT & ROUTERS["routers/"]

    SCHEMA --> CORE & PROVIDERS & SERVICES
    HELPERS --> CORE & PROVIDERS & SERVICES
    CORE --> SERVICES
    PROVIDERS --> SERVICES
    SERVICES --> ROUTERS

    UI["UI"] -- HTTP Request --> ROUTERS
    ROUTERS -- HTTP Response --> UI

Import Permission Table:

Module Can Import From Blind To
config/ .env (data only) everything
schema/ config/ core, providers, services, routers
helpers/ config/ core, providers, services, routers
core/ config/, schema/, helpers/ providers/, services/, routers/
providers/ config/, schema/, helpers/ core/, services/, routers/
services/ config/, schema/, helpers/, core/, providers/ routers/
routers/ services/, schema/ core/, providers/, helpers/
main.py config/, routers/ internal business logic

3. The Structural Blueprint (Dependency & Directory Rules)

3.1 Dependency Rule

"Imports flow in one direction"

The 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.

1. Top-level Isolation

Each 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.

2. Layer Trust / Unidirectional Flow

The Core Truth:

  • root/.env is the Single Source of Truth for project environment variables. It manipulates src/config/settings.py. For example: LOG_DIR=logs, JINA_API_KEY=abcd
  • src/config/:
    • src/config/settings.py is the gearbox of the entire project. The environment driver controls the project through this gearbox.
      (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))
    • src/config/dotenv.py
    • src/config/__init__.py
  • src/schema/: 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.

Dependency Privacy:

  • src/{module}/helpers/: Each module can have its own helpers/ folder. These helpers are entirely private. Meaning, one module like src/api/* or src/api/__init__.py will never import or call the private helpers of another module like src/{module}/helpers/*. These helpers can only be called by their respective src/{module}/*.
  • src/helpers/: If any global helper logic (e.g., date formatting, logging) is needed across multiple modules, it belongs in the project root src/helpers/. Everyone is allowed to import or call these globally.

Core Infrastructures:

  • src/core/: Knows src/schema/__init__.py, src/config/__init__.py, and src/helpers/.
  • src/providers/: Knows src/schema/__init__.py, src/config/__init__.py, and src/helpers/. Peer of core/ — they are blind to each other.
  • src/services/: The fan-in point. Knows src/core/__init__.py, src/providers/__init__.py, src/schema/__init__.py, src/config/__init__.py, and src/helpers/. This is where core/ and providers/ converge.
  • src/routers/: Only knows src/services/__init__.py and src/schema/__init__.py. No business logic — HTTP interface only.
  • src/api/frontend/: Merely used to represent src/services/* to the frontend.
  • src/tools/: 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/services/*. They take arguments as input and return structured outputs.

3.2 Directory Structure Rules

Rule 1 — Directory Name = Its Responsibility A directory's name strictly defines its single responsibility. All scripts inside that directory must cover the sub-responsibilities of that exact context.

providers/    ← AI/external service integrations ONLY
core/         ← Business logic ONLY
helpers/      ← Global utilities that assist the entire project ONLY
config/       ← All configuration ONLY
tools/        ← Reusable standalone operations ONLY

Rule 2 — /config/ is the Single Source of Truth If there are hardcoded or scattered parameters anywhere in the project, they must be migrated to /config/. The __init__.py file aggregates and exposes all configs.

# ❌ Avoid
MODEL = "gpt-4o"  # hardcoded inside core/agent.py

# ✅ Prefer
class LLMConfig(BaseSettings):
    model: str = "gpt-4o"

Rule 3 — Sub-Responsibility Allowed, Cross-Responsibility Forbidden

providers/
├── openai.py        ✅ Sub-responsibility of "providers"
├── anthropic.py     ✅ Sub-responsibility of "providers"
└── formatter.py     ❌ This is the job of helpers/

Cross-Responsibility Violation — Detection & Fix:

# ❌ Violation
helpers/
└── gemini_caller.py     ← AI Provider call — what is this doing in helpers/?

# ✅ After fix
providers/
└── gemini.py            ← Migrated to the correct location

4. Coding Guidelines (Safety, Performance, Security)

4.1 Type Safety

[!WARNING]
Ambiguity kills maintainability.

Always utilize Pydantic models and Python Type Hints. The code must be completely mypy / pyright error-free.

# ❌ Avoid
data: dict = {}
value: Any = get_value()

# ✅ Prefer
data: UserConfig = UserConfig(...)
value: ResponsePayload = get_value()

If using raw dict or Any is unavoidable, there must be a clear and explicit justification.

4.2 Boundary Defense & Null Elimination (The Tony Hoare Rule)

"I call it my billion-dollar mistake. It was the invention of the null reference in 1965." — Sir Tony Hoare
"Don't check for None repeatedly — eliminate None at the boundary."

Never allow defensive, repetitive None checks to pollute core business logic.

  • 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()).
  • Guaranteed Invariants Inside the Core: Once past the entry boundary, assume entities are valid, non-null objects. Core logic should never fear None.
  • Prohibited: Never scatter obj.field if obj else default across downstream calculations or rendering passes.
# ❌ Avoid (Noisy defensive checks polluting business logic)
def process(context):
    mode = context.canvas.mode if context.canvas else "blur"
    intensity = context.canvas.blur_intensity if context.canvas else 30
    darken = context.canvas.darken_alpha if context.canvas else 0.25

# ✅ Prefer (Tony Hoare Boundary Defense / Null Object Pattern)
def process(context):
    # Eliminate None once at the entry boundary:
    canvas = context.template.canvas if (context.template and context.template.canvas) else CanvasConfig()

    # Pure business logic — zero null-checking noise:
    mode = canvas.mode
    intensity = canvas.blur_intensity
    darken = canvas.darken_alpha

4.3 Performance & Determinism

"Fast by design, not by accident."

The system design will be ultra-fast and must follow an extensible pattern in all scenarios.

  • [ ] Adding a new provider requires zero modifications to the core.
  • [ ] Configuration-driven behavior — hardcoded values are prohibited.
  • [ ] Async-first — always use async/await for I/O bound operations.
  • [ ] Implement lazy loading wherever applicable.

4.4 Robustness

"New features must land on solid ground."

Adding a new feature = existing code remains untouched, only new modules/layers are extended.

Schema First → Clean Interfaces → Stable Core → Safe Extensions

Every component must possess:

  • [ ] Structured error handling (try/except with typed exceptions).
  • [ ] Meaningful logging — print() is prohibited. Consolidate logs by layer (e.g., service.log, router.log) instead of per-script.
  • [ ] Graceful degradation — a single failure will not bring down the entire system.

4.5 Security-Safety Practices

"Security is a first-class citizen, not an afterthought."
With Comprehensive test coverage that is maintained continuously

Risk Mitigation Strategy
Injection Attacks (SQL/Command/Shell) Never concatenate user input directly into executable strings. Always use Parameterized queries, ORM, or Safe execution APIs.
Path Traversal When accessing the file system, sanitize any user-provided path inputs and strictly enforce sandbox boundaries to block access outside permitted directories.
Secret Leakage Never hardcode API Keys or Credentials in the source code. Always use Environment Variables (.env) or a Secret Manager.
Rate Limiting & Abuse Enforce request rate sizing limit restrictions and payload thresholds on all public/external APIs.
Failover & Stability Implement Error Retry Logic with Exponential Backoff to prevent system crashes triggered by network failures during third-party or external API calls.

5. Code Craftsmanship & Maintenance

5.1 Advanced Refactoring & Code Evolution

"Refactoring is a deliberate process, not a quick fix."

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.

Before You Begin

Before 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.

The Master Refactoring Strategy

[!IMPORTANT]
Method Extraction & Clean-up: Long method decomposition • Complex conditional extraction • Loop body extraction • Duplicate code consolidation • Guard clause introduction • Command query separation.

  • Design Pattern Application: Apply Strategy, Factory, Observer, or Decorator patterns. Eliminate hardcoded if-else or switch/case logic using Replace Conditional with Polymorphism or Replace Type Code with Subclasses.
  • API & Database Optimization:
    • API: Ensure Endpoint consolidation, Error handling standardization, Versioning strategy, and firmly maintain backward compatibility.
    • Database: Boost performance using Query simplification, Schema normalization, Index optimization, and Caching strategies (Lazy evaluation).
  • 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.
  • 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.

6. Verification & Testing

Testing 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:

  • Golden Master / 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.
  • 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.
  • Performance Testing: Validate whether the system design is genuinely ultra-fast. Measure if I/O bound operations during loads are triggering blocking issues.
  • 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.
  • Integration Validation: Validate that end-to-end data flow operates perfectly when different modules — specifically the services/, providers/, and database layers — interact simultaneously.
  • 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.

[!NOTE]

  • For project tree examples and relationships, follow: .agents/rules/project-tree-example.md
  • For project configuration example follow: .agents/rules/project-config-example.md

04 同仓库更多 Skills

mdnaimul22
mdnaimul22/human-skills

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.

★ 3
mdnaimul22
mdnaimul22/human-skills

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.

★ 3
mdnaimul22
mdnaimul22/human-skills

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 「复刻这个视频」「照着这个视频做一个」.

★ 3
mdnaimul22
mdnaimul22/human-skills

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.

★ 3
mdnaimul22
mdnaimul22/human-skills

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/integration/contract/E2E/smoke classification, bug-to-test regression protection, consumer/provider contract testing, test-necessity review, and pre-delivery evidence review.

★ 3
mdnaimul22
mdnaimul22/human-skills

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/Linear/Taiga but needs structured delivery tracking.

★ 3