Common Technical Practices
Developmentcommon-technical-practicesCommon Technical Practices is an Agent Skill for development published in the TencentBlueKing/bk-ci repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
处理 BK-CI 后端中的横切技术实践时使用,例如 AOP、分布式锁、重试、参数校验、性能监控、定时任务和审计日志。当用户要实现这类框架级实践而不是具体业务功能时优先使用。
QUICK START
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/TencentBlueKing/bk-ci/blob/HEAD/ai/skills/common-technical-practices/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/common-technical-practices, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
通用技术实践
适用场景
- 添加 AOP 切面
- 使用分布式锁控制并发
- 配置重试机制与退避策略
- 做接口参数校验
- 添加性能监控埋点
- 编写定时任务
- 记录审计日志
不适用场景
- 只是使用某个具体工具类,例如 JWT、表达式解析、线程池工具
- 只是微服务之间的调用、事件驱动或多环境配置
- 只是某个模块自己的业务规则
快速指导
- 这个 skill 关注的是“框架级横切实践”,不是具体业务模块。
- 如果问题更像“给业务逻辑增加一层通用能力”,通常落在这里。
- 先按主题进入对应参考文档:
- AOP:
reference/1-aop-aspect.md - 分布式锁:
reference/2-distributed-lock.md - 重试:
reference/3-retry-mechanism.md - 参数校验:
reference/4-parameter-validation.md - 性能监控:
reference/5-performance-monitoring.md - 定时任务:
reference/6-scheduled-tasks.md - 审计日志:
reference/7-audit-logging.md
- AOP:
- 如果你要的是“某个现成组件怎么用”,切到
utility-components;如果你要的是“微服务基础能力怎么搭”,切到microservice-infrastructure。
高信号规则
- AOP、锁、重试、监控、审计这类能力通常跨多个模块复用
- 这类实践往往和 Spring / 框架集成方式强相关
- 落地时要优先考虑幂等性、可观测性和并发安全
- 不要把横切能力写死在单个业务类里
关键陷阱
- 把工具类使用问题误放到这里
- 只实现功能,不处理幂等、超时、并发和可观测性
- 重试、锁、定时任务直接上,而不先判断是否真的需要
- 把审计日志、监控埋点散落在业务代码里,后续难以维护
延伸阅读
- AOP:
reference/1-aop-aspect.md - 分布式锁:
reference/2-distributed-lock.md - 重试:
reference/3-retry-mechanism.md - 参数校验:
reference/4-parameter-validation.md - 性能监控:
reference/5-performance-monitoring.md - 定时任务:
reference/6-scheduled-tasks.md - 审计日志:
reference/7-audit-logging.md - 如果你需要的是工具组件:再看
utility-components - 如果你需要的是微服务底座:再看
microservice-infrastructure