用途
该技能用于在开发 Julia 包时提供指导,确保遵循正确的开发工作流、测试模式、文档标准与性能最佳实践。当进行 Julia 包开发、编写 Julia 测试、为 Julia 函数撰写文档、搭建 Julia 包基础设施、使用 Distributions.jl、Turing.jl 或 SciML 相关包,以及优化 Julia 代码性能时,可启用此技能。该技能提供 Julia 专属的开发模式;项目特定的架构与领域知识应保留在项目的 CLAUDE.md 文件中。
开发工作流
环境管理方面,可使用 julia --project=. 启动带项目环境的 Julia,在 REPL 中通过 using Pkg; Pkg.activate(".") 激活项目,使用 Pkg.instantiate() 安装依赖。更新依赖推荐使用 Pkg.update(),而非直接编辑 Project.toml;添加新依赖使用 Pkg.add("PackageName");添加开发依赖使用 Pkg.add("PackageName"; io=devnull) 后手动移至 extras/test 依赖;使用 Pkg.status() 检查包状态。资料强调:始终使用 Pkg.update() 更新包,切勿直接编辑 Project.toml 进行版本更新。
测试方面,可在项目根目录运行 julia --project=. -e 'using Pkg; Pkg.test()' 执行全部测试;使用测试环境运行 julia --project=test test/runtests.jl;如支持,可运行 julia --project=test test/runtests.jl skip_quality 跳过质量检查。测试组织建议使用 TestItemRunner 与 @testitem 语法进行模块化测试,按组件组织(test/component/、test/package/),包级测试放在 test/package/ 用于质量检查(Aqua、DocTest、格式化),使用 @testitem "description" begin ... end 定义单个测试项。
文档方面,可本地构建文档 julia --project=docs docs/make.jl,跳过 notebook 加速构建 julia --project=docs docs/make.jl --skip-notebooks 或通过环境变量 SKIP_NOTEBOOKS=true julia --project=docs docs/make.jl。文档结构使用 Documenter.jl,通过 CI 自动部署到 GitHub Pages,结构定义在 docs/pages.jl 或 docs/make.jl 中。
代码质量方面,可运行 pre-commit run --all-files 执行预提交钩子;JuliaFormatter 通常由 pre-commit 钩子处理。质量检查包括 Aqua.jl 包质量测试、JuliaFormatter.jl 代码格式化、pre-commit 钩子自动检查。
代码风格指南
遵循 SciML(科学机器学习)编码标准:避免类型不稳定、确保高效预编译、为性能使用适当的类型注解、编写类型稳定的代码。资料给出了类型稳定与不稳定的对比示例。格式化规则包括:每行最多 80 字符、无尾随空白、无多余空行、使用 JuliaFormatter.jl 保持一致格式。
文档标准
文档字符串语法使用 @doc 配合原始字符串或常规字符串。对于不含 LaTeX 或模板的简单文档字符串使用常规字符串;包含 LaTeX 数学公式时使用 @doc raw" 原始字符串以保留反斜杠。
DocStringExtensions 模板展开规则:使用 @doc "(常规字符串)用于模板(允许展开);将模板与 LaTeX 结合时使用 @doc """ 并转义反斜杠;切勿使用 @doc raw" 配合模板(会阻止展开)。
文档结构最佳实践:保持接口方法文档字符串简洁(1-2 行);使用 "See also" 部分进行交叉引用;避免相关函数(pdf/logpdf、cdf/logcdf)之间的重复;在主类型/构造函数文档字符串中包含数学公式;使用 @example 块提供最小但足够的示例。
包结构
典型 Julia 包结构包含:src/(主模块文件与导出、组件实现、docstrings.jl 模板、utils/)、test/(主测试文件、按组件的测试、质量测试)、docs/(构建脚本、文档源、页面结构)、Project.toml、README.md。
性能最佳实践
类型稳定性方面,可使用 @code_warntype my_function(args...) 检查类型稳定性,查找红色(Any)类型以识别类型不稳定。预编译方面,使用 PrecompileTools.jl 处理复杂包,通过 @compile_workload 定义代表性工作负载。性能模式包括:尽可能使用原地操作(! 后缀约定)、为循环预分配数组、在安全时使用 @simd 与 @inbounds、对小规模固定大小数组考虑 StaticArrays.jl、使用 @time 与 @benchmark(BenchmarkTools.jl)进行性能分析。
常见依赖与模式
实现分布时,需实现必需方法:pdf、logpdf、cdf、logcdf、quantile、rand;实现支持方法:minimum、maximum、insupport;可选实现:mean、var、std(若解析上可行);向量化通过广播自动处理;考虑专用批处理方法:pdf!、logpdf!、cdf!。
Turing.jl 与自动微分兼容性方面,需确保与自动微分兼容:ForwardDiff.jl、ReverseDiff.jl、Zygote.jl、Enzyme.jl;在 AD 敏感代码中避免不可微操作。
常见 Julia 生态工具
Pkg(包管理)、TestItemRunner(现代测试框架)、Documenter.jl(文档生成)、DocStringExtensions(文档模板)、JuliaFormatter.jl(代码格式化)、Aqua.jl(包质量测试)、BenchmarkTools.jl(性能基准测试)、PrecompileTools.jl(预编译优化)。
限制
资料未提供该技能的具体安装命令、收费方式、价格、平台支持范围或实际使用效果等信息,这些内容暂未提供。