AgentSkillsCN

conventions

本项目的编码规范与黄金法则。当 Claude 编写代码时，会自动加载这些规则。

SKILL.md
--- frontmatter
name: conventions
description: Coding conventions and golden rules for this project. Auto-loaded when Claude writes code.
user-invocable: false

Project Conventions

Golden Rules

Enforced by pre-commit hooks (block commits)

  1. •No file > 500 lines → Split into smaller modules
  2. •No print() / console.log() → Use logger.info("msg", extra={...})
  3. •No TODO without issue → # TODO(#123): description
  4. •No secrets in code → Use environment variables
  5. •No function > 50 lines → Extract helpers, each does one thing
  6. •No magic numbers → Extract to named constant
  7. •No cross-layer imports → Respect architecture boundaries (requires .import-boundaries.json)

Not yet mechanically enforced (follow as guidelines)

  1. •No Any without comment → Add type annotation or explain why

Naming

  • •Python: snake_case for functions/variables, PascalCase for classes
  • •TypeScript: camelCase for functions/variables, PascalCase for classes/interfaces
  • •Files: kebab-case for non-class files, PascalCase for class files
  • •Tests: test_<module>_<behavior>.py or <module>.test.ts

Structure

  • •Business logic in src/services/
  • •API handlers in src/routes/ or src/api/
  • •Data models in src/models/
  • •Shared utilities in src/utils/ (only if used by 3+ modules)
  • •Tests mirror src/ structure under tests/

Error Handling

  • •Use typed exceptions, not generic Exception
  • •Log errors with context: logger.error("msg", extra={"user_id": uid, "action": "login"})
  • •Return appropriate HTTP status codes (don't swallow errors)
  • •Fail fast on invalid input at system boundaries

Testing

  • •Test writer is separate from implementer
  • •Tests see interfaces, not implementation
  • •One assertion per test (or one logical behavior)
  • •No test depends on execution order
  • •Mock external services, not internal modules