Coding Conventions-北京尧图网络

Coding Conventions【免费下载链接】get-shit-doneA light-weight and powerful meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.项目地址: https://gitcode.com/GitHub_Trending/getshi/get-shit-doneAnalysis Date:[YYYY-MM-DD][YYYY-MM-DD] 必须替换为 mapper 提示词中 Todays date: 行提供的日期。[gsd-codebase-mapper](https://link.gitcode.com/i/3909d9b4145d86a34b8f0f1505c08518) 的 write_documents 步骤有硬性约束NEVER guess or infer the date — always use the exact date from the prompt. 文档结尾同样以 *Convention analysis: [date]* 与 *Update when patterns change* 收尾提示这是一份活文档模式变化时需刷新。 ### 1. Naming Patterns命名模式模板将命名规则拆为四组每组给出三类典型条目 - **Files文件**如 kebab-case for all files、Test files: *.test.ts alongside source、Components: PascalCase.tsx for React components。 - **Functions函数**如 camelCase for all functions、no special prefix for async functions、handleEventName for event handlers。 - **Variables变量**如 camelCase for variables、UPPER_SNAKE_CASE for constants、私有成员用 _ 前缀还是不用需明确记录no prefix 也是结论。 - **Types类型**如接口 PascalCase, no I prefix、类型别名 PascalCase for type aliases、枚举 PascalCase for enum name, UPPER_CASE for values。填写要点是**穷举式记录**每一类都要写明是什么和反例是什么例如私有成员不加下划线前缀本身就是有价值的约定。 ### 2. Code Style代码风格分两块均以工具配置文件关键规则的形式记录 - **Formatting格式化**格式化工具Prettier with config in .prettierrc、行长上限100 characters max、引号风格single quotes for strings、分号策略required 或 omitted。 - **Linting静态检查**工具与配置文件ESLint with eslint.config.js、规则集extends airbnb-base, no console in production、触发命令npm run lint。模板中这些条目直接指向 .prettierrc、eslint.config.js 等真实配置文件——这也与 [gsd-codebase-mapper](https://link.gitcode.com/i/3909d9b4145d86a34b8f0f1505c08518) 在 quality 焦点下的探索命令一一对应后文生成链路一节详述。 ### 3. Import Organization导入组织记录四件事 1. **Order顺序**模板给出的示例分四层——① 外部包react、express 等② 内部模块/lib、/components③ 相对导入., ..④ 类型导入import type {}。 2. **Grouping分组**如 blank line between groups、alphabetical within each group。 3. **Path Aliases路径别名**如 / for src/, components/ for src/components/。这一节对 Agent 的意义在于新文件的 import 块可以直接按模板拼装无需再从上下文猜测。 ### 4. Error Handling错误处理 - **Patterns模式**策略throw errors, catch at boundaries、自定义错误extend Error class, named *Error、异步处理use try/catch, no .catch() chains。 - **Error Types错误类型决策**何时 throwinvalid input, missing dependencies、何时用返回值表达预期失败expected failures return ResultT, E、记录日志log error with context before throwing。 ### 5. Logging日志 - **Framework**工具console.log, pino, winston与级别debug, info, warn, error。 - **Patterns**格式structured logging with context object、时机log state transitions, external calls、位置log at service boundaries, not in utils。 ### 6. Comments注释模板给出三个子节 - **When to Comment**explain why, not what、记录业务逻辑/算法/边界情况、避免 // increment counter 这类显而易见注释。 - **JSDoc/TSDoc**使用范围required for public APIs, optional for internal与格式use param, returns, throws tags。 - **TODO Comments**格式约定如 // TODO(username): description与追踪方式link to issue number if available。 ### 7. Function Design函数设计三个量化维度 - **Size**如 keep under 50 lines, extract helpers - **Parameters**如 max 3 parameters, use object for more、destructure objects in parameter list - **Return Values**如 explicit returns, no implicit undefined、return early for guard clauses。 ### 8. Module Design模块设计 - **Exports**如 named exports preferred, default exports for React components、export from index.ts for public API。 - **Barrel Files桶文件**如 use index.ts to re-export public API、avoid circular dependencies。 ## 官方 Good Example一份填写完成的 CONVENTIONS.md 模板文档在 good_examples 块中附了一份完整填写示例Analysis Date 2025-01-20是骨架 → 成品的参照标准。摘录其中信息密度最高的几节展示填写到位的粒度 markdown ## Naming Patterns **Files:** - kebab-case for all files (command-handler.ts, user-service.ts) - *.test.ts alongside source files - index.ts for barrel exports **Functions:** - camelCase for all functions - No special prefix for async functions - handleEventName for event handlers (handleClick, handleSubmit) **Variables:** - camelCase for variables - UPPER_SNAKE_CASE for constants (MAX_RETRIES, API_BASE_URL) - No underscore prefix (no private marker in TS) **Types:** - PascalCase for interfaces, no I prefix (User, not IUser) - PascalCase for type aliases (UserConfig, ResponseData) - PascalCase for enum names, UPPER_CASE for values (Status.PENDING) ## Code Style **Formatting:** - Prettier with .prettierrc - 100 character line length - Single quotes for strings - Semicolons required - 2 space indentation **Linting:** - ESLint with eslint.config.js - Extends typescript-eslint/recommended - No console.log in production code (use logger) - Run: npm run lint ## Error Handling **Patterns:** - Throw errors, catch at boundaries (route handlers, main functions) - Extend Error class for custom errors (ValidationError, NotFoundError) - Async functions use try/catch, no .catch() chains **Error Types:** - Throw on invalid input, missing dependencies, invariant violations - Log error with context before throwing: logger.error({ err, userId }, Failed to process) - Include cause in error message: new Error(Failed to X, { cause: originalError }) ## Logging **Framework:** - pino logger instance exported from lib/logger.ts - Levels: debug, info, warn, error (no trace) **Patterns:** - Structured logging with context: logger.info({ userId, action }, User action) - Log at service boundaries, not in utility functions - Log state transitions, external API calls, errors - No console.log in committed code ## Function Design **Parameters:** - Max 3 parameters - Use options object for 4 parameters: function create(options: CreateOptions) - Destructure in parameter list: function process({ id, name }: ProcessParams)这份示例体现的填写标准有三点值得记住每条约定都带具体文件名/代码示例如command-handler.ts、lib/logger.ts每条约定都是可直接执行的祈使句对否定项同样明确no.catch()chains、No console.log in committed code。填写准则guidelines块的完整规则模板文档的guidelines块定义了填写与使用规则是保证文档质量的元规范。什么该写进来 / 什么不该写进来What belongs in CONVENTIONS.md代码库中观察到的命名模式Naming patterns格式化规则Prettier config、linting rules导入组织模式Import organization patterns错误处理策略Error handling strategy日志方案Logging approach注释约定Comment conventions函数与模块设计模式Function and module design patternsWhat does NOT belong here作用域边界内容归属文档架构决策ARCHITECTURE.md技术选型STACK.md测试模式TESTING.md文件组织STRUCTURE.md这张分工表正是七文档体系的核心设计每份文档职责单一gsd-codebase-mapper 在quality焦点下同时产出 CONVENTIONS.md 与 TESTING.md 时就靠这条边界避免两份文档内容互相污染。填写时的操作步骤Check.prettierrc,.eslintrc, or similar config files——先看配置文件定格式与 Lint 事实Examine 5-10 representative source files for patterns——抽样 5~10 个有代表性的源文件归纳模式Look for consistency: if 80% follows a pattern, document it——以 80% 遵循率为阈值判断这是不是约定Be prescriptive: Use X not Sometimes Y is used——规定式表达Note deviations: Legacy code uses Y, new code should use X——对偏离现状要显式标注存量用 Y新代码用 XKeep under ~150 lines total——全文控制在约 150 行以内保证后续被 Agent 完整读入上下文时的成本可控。什么阶段规划时最有价值模板明确列出五类场景Writing new code匹配现有风格Adding features遵循命名模式Refactoring应用一致的约定Code review对照文档化模式做检查Onboarding快速理解风格预期分析流程Analysis approach模板给出的标准扫描步骤扫描src/目录的文件命名模式检查package.jsonscripts 中的 lint/format 命令读 5~10 个文件识别函数命名与错误处理方式查看配置文件.prettierrc、eslint.config.js记录 import、注释、函数签名中的模式。这些步骤与 gsd-codebase-mapper 中quality焦点的探索命令块严格对齐# Linting/formatting config ls .eslintrc* .prettierrc* eslint.config.* biome.json 2/dev/null cat .prettierrc 2/dev/null # Test files and config ls jest.config.* vitest.config.* 2/dev/null find . -name *.test.* -o -name *.spec.* | head -30 # Sample source files for convention analysis ls src/**/*.ts 2/dev/null | head -10生成链路/gsd:map-codebase 如何产出 CONVENTIONS.md模板不是给人手敲的而是被工作流调用的。map-codebase 工作流的编排逻辑如下。第一步init 上下文。工作流先执行gsd-sdk query init.map-codebase拿到mapper_model、codebase_dir、has_maps、existing_maps、subagent_timeout、date等字段并通过gsd-sdk query agent-skills gsd-codebase-mapper注入项目技能上下文。第二步已存在时的三选一。若.planning/codebase/已存在工作流询问用户 Refresh删除重扫/ Update只更新指定文档/ Skip沿用。第三步并行派发 4 个 mapper 代理。工作流使用Agent工具以run_in_backgroundtrue并行拉起 4 个 gsd-codebase-mapper 子代理每个代理负责一个 focus 领域代理Focus产出文档Agent 1techSTACK.md, INTEGRATIONS.mdAgent 2archARCHITECTURE.md, STRUCTURE.mdAgent 3qualityCONVENTIONS.md, TESTING.mdAgent 4concernsCONCERNS.md其中产出 CONVENTIONS.md 的 Agent 3 提示词形态如下摘自 map-codebase.md 的spawn_agents步骤Focus: quality Todays date: {date} Analyze this codebase for coding conventions and testing patterns. Write these documents to .planning/codebase/: - CONVENTIONS.md - Code style, naming, patterns, error handling - TESTING.md - Framework, structure, mocking, coverage IMPORTANT: Use {date} for all [YYYY-MM-DD] date placeholders in documents. Scope: {full repo | --paths 限定前缀} — when --paths is supplied, restrict exploration to those prefixes only. Explore thoroughly. Write documents directly using templates. Return confirmation only.【免费下载链接】get-shit-doneA light-weight and powerful meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.项目地址: https://gitcode.com/GitHub_Trending/getshi/get-shit-done创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Coding Conventions

相关推荐

Calibre 格式转换教程：30 秒把 PDF 变成手机 EPUB

Claude Code Router 怎么接入 Kimi CLI 并用 /model 在多个可用模型间切换

如何用 bulk-rnaseq 技能把定量输出汇总成 PyDESeq2 可用的基因计数矩阵

更多资讯

LMX2594 GPIO模拟SPI寄存器写入时序设计

CANN/GE内存加载模型API文档

sglang-kernel（sgl-kernel）内核库完全指南：安装构建、新增算子开发流程与体积分析

Awesome Copilot 实战：用 APPSYNC_JS 运行时构建生产级 AWS AppSync Event API 处理器（onPublish/onSubscribe 全指南）

Carbon 2021 路线图解读：从实验到可执行证据的加速路径

草莓腐烂二分类模型：轻量CNN实战与产线部署

今日更新

CopilotKit Vue Demo 与 React Demo 的 Parity 实现指南：路由、运行时端点与交互语义的全框架对齐

Harbor RBAC 实战：db_auth 模式下非管理员用户管理项目成员的完整验证与权限模型解析

STM32平衡车纯平衡程序从拆包到参数整定的完整调试指南

本周精选

超人会飞不算本事：系统稳定依赖清晰规则与边界设计

超人VS蜘蛛侠：拆解超级IP的影响力与传播方法论

基于CNN的调制信号识别：MATLAB实现时频图分类实战

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？