编码标准
- 作者仓库星标 0
- 作者仓库 skills-registry
- 领域
- 人工智能
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @tomevault-io · 未声明许可证
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 即装即用
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- 未声明(默认跨平台)
- 运行环境要求
- Python >=3.10
- 检测到的文件与系统行为
-
- 只读
- 读取环境变量
- 网络行为
- 仅限本地
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
---
name: coding-standards
description: Use when writing or reviewing code in any language. Covers typed-language rules (TypeScript, Python, Go), naming conventions, file organisation, error handling, import ordering, and universal quality rules. Read project conventions first to identify the stack, then apply only the relevant language sections.
---
# Coding Standards
> Before reviewing, read `copilot-instructions.md` / `AGENTS.md` / `CLAUDE.md` to identify the project's language, framework, and version. Adapt stack-specific rules accordingly.
## Typed Language Rules (apply only when project uses the language)
**TypeScript**
- Strict mode required — never disable `strict: true`
- No `any` without comment explaining why unavoidable
- No `@ts-ignore` without comment
- Use `unknown` + narrowing instead of `any` when type genuinely unknown
- `interface` for object shapes; `type` for unions, intersections, utilities
- All exported functions: explicit return type annotations
**Python**
- Type hints required on all function signatures (`def fn(x: int) -> str:`)
- No `# type: ignore` without explanatory comment
- Use `T | None` (Python 3.10+) or `Optional[T]` — no implicit `None` returns
- Use `dataclasses` or `pydantic` for structured data shapes
**Go**
- All errors must be checked — never discard with `_` unless intentional + commented
- Exported identifiers must have doc comments
- No `interface{}` / `any` without justification
- Prefer table-driven tests; use `errors.Is`/`errors.As` for error checking
## Naming Conventions
| Thing | Convention | Example |
|-------|-----------|---------|
| UI components / classes | PascalCase | `UserCard`, `NoteEditor` |
| Utility / helper files | kebab-case | `sync-messages.ts`, `format-date.py` |
| Variables and functions | camelCase | `activeUser`, `loadData()` |
| Module-level constants | UPPER_SNAKE_CASE | `MAX_RETRIES` |
| Type / interface names | PascalCase | `UserSchema`, `ApiResponse` |
| Route / endpoint files | Follow framework convention | `+page.server.ts`, `router.py` |
## File Organisation
- Group by feature/domain, not by type
- One exported component per file
- Target under 400 lines per file; split larger files by concern
- Before creating a new file, check if logic fits in an existing module
## Error Handling
- Never empty `catch` blocks — re-throw, log, or return structured error
- Server errors: log with context server-side; return safe message to client (no stack traces, no internal paths)
- API routes: return appropriate HTTP status codes with structured error body
- Validate all user input at system boundaries before use
## Security (non-negotiable)
- No hardcoded secrets, credentials, or API keys — use environment variables
- Parameterized queries only — never interpolate user input into SQL/queries
- Sanitize user-controlled HTML before rendering (DOMPurify or equivalent)
- Never return stack traces or internal paths to the client
## Import Ordering
Groups separated by a blank line:
1. External packages / standard library
2. Framework internals
3. Internal path aliases
4. Relative imports
## Code Quality
- Functions under 50 lines, single responsibility
- No dead code, unused imports, or commented-out blocks in commits
- No logic repeated at 3+ call sites without extraction into a named helper
- Comment the *why*, not the *what*
## What Never to Do
- No syntax from the wrong framework version — check project conventions
- No untyped code where the language supports type annotations
- No hardcoded environment-specific values
- No deprecated APIs without a migration comment
---
> Source: [AshenDulsanka/agent-arche](https://github.com/AshenDulsanka/agent-arche) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-05-22 -->
章节与文件索引
按说明文件中的顺序排列。
类型化语言规则(仅当项目使用该语言时适用)
命名约定
文件组织
错误处理
安全(不可协商)
文件/命令 -> copilot-instructions.md · AGENTS.md · CLAUDE.md · strict: true · any · @ts-ignore · unknown · interface
内容校验值 -> 56b188a90b31
当前原文的自动摘译,尚未人工审校。
类型化语言规则(仅当项目使用该语言时适用)
需要 TypeScript 严格模式 — 永远不要禁用
strict: true否any没有注释解释为什么不可避免 否@ts-ignore没有注释 当类型真正未知时使用unknown+ 缩小而不是any命名约定
事物 · 约定 · 示例 UI 组件/类 · PascalCase ·
UserCard、NoteEditor实用程序/帮助文件 · kebab-case ·sync-messages.ts、format-date.py变量和函数 · 驼峰命名法 ·activeUser、loadData()模块级常量 · UPPER_SNAKE_CASE ·MAX_RETRIES文件组织
按功能/域分组,而不是按类型分组 每个文件一个导出的组件 每个文件目标在 400 行以下;按关注点拆分较大的文件 在创建新文件之前,检查逻辑是否适合现有模块
错误处理
永远不要清空
catch块——重新抛出、记录或返回结构化错误服务器错误:使用上下文服务器端记录;向客户端返回安全消息(无堆栈跟踪,无内部路径) API 路由:返回带有结构化错误正文的适当 HTTP 状态代码 使用前在系统边界验证所有用户输入安全(不可协商)
没有硬编码的秘密、凭据或 API 密钥 - 使用环境变量 仅参数化查询 - 绝不将用户输入插入 SQL/查询 在渲染之前清理用户控制的 HTML(DOMPurify 或等效项) 绝不将堆栈跟踪或内部路径返回给客户端