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/.envis the Single Source of Truth for project environment variables. It manipulatessrc/config/settings.py. For example:LOG_DIR=logs,JINA_API_KEY=abcdsrc/config/:src/config/settings.pyis 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.pysrc/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 ownhelpers/folder. These helpers are entirely private. Meaning, one module likesrc/api/*orsrc/api/__init__.pywill never import or call the private helpers of another module likesrc/{module}/helpers/*. Thesehelperscan only be called by their respectivesrc/{module}/*.src/helpers/: If any global helper logic (e.g., date formatting, logging) is needed across multiple modules, it belongs in the project rootsrc/helpers/. Everyone is allowed to import or call these globally.
Core Infrastructures:
src/core/: Knowssrc/schema/__init__.py,src/config/__init__.py, andsrc/helpers/.src/providers/: Knowssrc/schema/__init__.py,src/config/__init__.py, andsrc/helpers/. Peer ofcore/— they are blind to each other.src/services/: The fan-in point. Knowssrc/core/__init__.py,src/providers/__init__.py,src/schema/__init__.py,src/config/__init__.py, andsrc/helpers/. This is wherecore/andproviders/converge.src/routers/: Only knowssrc/services/__init__.pyandsrc/schema/__init__.py. No business logic — HTTP interface only.src/api/frontend/: Merely used to representsrc/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 callssrc/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
dictorAnyis 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 defaultacross 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/awaitfor 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/exceptwith 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, orDecoratorpatterns. 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/, anddatabaselayers — interact simultaneously. - Memory Optimization & Resource Pooling: Ensure proper connection pooling for database or external API calls. Maintain resource cleanup (e.g., using
finallyblocks orasync withcontext 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
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.
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.
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 「复刻这个视频」「照着这个视频做一个」.
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.
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.
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.