We are the Kangaroo Cloud Data Stack UED team, committed to creating excellent one-stop data middle-end products. We always maintain the spirit of craftsmanship, explore front-end roads, and accumulate and spread experience value to the community.
Author of this article: Liu Yi
For R&D teams who need to push ZenTao bug fixes to Gitlab, CI and OMP
ZenTao: Product BUG Management Platform
OMP: Internal Multi-Environment Management Platform (Deployment)
background
A bug fix may seem like just “changing a few lines of code”, but in fact it generally involves multiple actions across systems such as ZenTao, Yuque documentation, Git branches, abnormal code location, independent CodeReview, GitLab MR, GitLab CI and OMP deployment environments. Any link that relies solely on word-of-mouth agreements will easily cause the entire process link to break.
Bugfix Agent The goal is not to allow the Agent to operate automatically without restrictions, but to solidify the conventions of these systems and steps into aResumable, auditable, paused in times of uncertaintycomplete workflow.
The following description takes the internal link of the company as an example. You can refer to the design ideas for general scenarios.
Bugfix link
Daily bug fixing usually has three pain points:
- Information dispersion: Zen Tao phenomenon, Yuque technical documentation supplement, branch naming rules and switching, submission information specifications, MR description templates, acceptance conditions, etc. need to be manually spliced and executed or manually required to enter the next process after waiting for AI execution.
- External actions are irreversible: cutting branches, submitting, creating MRs, and deploying may be repeated due to retries or abnormal interruptions.
- Automation is easy to exceed authority: the OMP environment is not unique, the deployment service cannot be mapped, and there is insufficient evidence for bugfix change requirements. Continuing to “guess” is more likely to cause deviation than pausing.
Therefore, a useful Bugfix Agent The answer should not only be “how to fix it”, but also:
- Is there currently evidence to continue enforcement?
- Has this external action already been performed?
- Is it possible to recover from the correct stage after failure (Loop)?
- How to independently determine whether the repair matches the problem (Review)?
design goals
Goals and Constraints
Advance automatically, but do not make unauthorized decisions for others
Bugfix Agent The core principle is: automate deterministic steps and explicitly return uncertain decisions to the user.
| Target | Corresponding constraints |
|---|---|
| automatic advance | Actions such as Zen Tao, branching, repairing, MR, and deployment are connected in stages. |
| The user must confirm the modification idea before modifying the code, and the user must confirm the modification content before submitting; | |
| Sensitive steps are confirmed by the user to reduce rework; at the same time, it supports “fully automatic” delivery of the final result directly. | |
| No recurring side effects | Read the running status of MR and OMP before deployment, and existing products will not be re-created. |
| No blind guessing | productName Pause when missing, source branch does not exist, environment/service is not unique |
| Can be independently reviewed | Fix the separation of Agent and Reviewer, and control the submission limit of review conclusion. |
| Cross-host reuse | Codex and Claude Code share a business agreement, only the adapter is different |
process reliability
Reliability comes from stopping conditions, not more automatic operations
Often the most valuable part of a process isn’t “automating it”, but knowing when not to continue:
- There are code changes in the local git workspace and are suspended at this time.
- Reviewer cannot establish judgment evidence (up to two rounds of Loop) and does not force submission.
- CI and OMP are not requested by users and do not poll CI status/deployment status without authorization.
- OMP environment or service is not unique and not selected by default
These stopping conditions allow Bugfix Agent The behavior can be explained, and users can accurately grasp the process by seeing the reason for the suspension, completed content and matters that need to be confirmed, instead of letting the user end up facing an untraceable or complex retracement failure result.
Architecture design
Thin Skill, Sharing Protocol, Host Adapter
Bugfix Agent Instead of cramming all the rules into a single Agent, they are split into three levels:
Thin entrance skills
The entrance is only responsible for triggering and orchestration, and is not responsible for branch cutting, git commit, CI, OMP and other business details:
# Codex
$bugfix-workflow [OMP] [CI轮询]
# Claude Code
/bugfix-workflow [OMP] [CI轮询]
Natural language can also be triggered, but the most critical Bug ID still needs to be completed. The sub-product name and version can be inferred from ZenTao information. This not only retains the conversational user experience, but also avoids entering the wrong branch or environment when insufficient input information is entered.
sharing agreement
references/workflow-protocol.md is the only source of business rules. It defines:
- How to use ZenTao information to determine branch prefix
fixandhotfix - Branch preparation, customized identification delivery and source branch verification
- Query and continuous monitoring boundaries of CI and OMP
- Pause conditions, retry upper limit and unified external output format
To concentrate the rules in the protocol, Codex’s toml Agent and Claude Code’s Markdown Agent only retain roles, permissions and protocol entries to avoid the gradual drift of rules at both ends.
Running status
bugfix_run.py use repo + bugId Identify a run and persist processing branches, MR, CI, OMP and retries. Read the status before each git commit, push, create MR or submit deployment: if there is already a commit SHA, MR ID or OMP deployId, it will not be executed again.
Preserving the running state makes “try again” no longer equivalent to “create another MR or deploy again.”
Flexible configuration
- When the BUG is relatively simple, you can request
全自动Advance and output the results directly - When the BUG is checked and located in the local service, you can directly hand over the cumbersome actions such as cutting branches and creating MR after clarifying the idea.
Bugfix Agentimplement - When the BUG is simple and there are no abnormalities in the code that has been clearly modified, you can ask to skip the independent review step to save Tokens
Bugfix actual circulation
Read the factual basis and don’t change the code yet
Bugfix Agent Pass first zentao-api Get bug details; if the ZenTao content contains or provides a separate link to Yuque technical documentation, then use yuque-reader Read Yuque documents to add context. Then extract the Zen Tao title, phenomenon, recurrence path, affected version, key fields and acceptance points.
Branch preparation, protecting local work
Executed before any branch switch git status --porcelainpause when there are tracked, untracked, or temporary changes in the workspace to avoid automation overwriting local work.
The judgment of branch naming and source branches is left to git-branch-naming. Required before processing branch creation git fetch originit is necessary after switching to the source git pull. If the source only exists remotely, a tracking branch is created; if it exists neither locally nor remotely, it is paused.
For hotfixes, the source must be determined according to release branch rules. The customized identification after the version number in the source branch needs to be retained in the processing branch; the standard test branch v{迭代号} Not considered a custom logo.
Separation of execution and review
Execute Agent bugfix-worker Use first superpowers:systematic-debugging Establish code root cause evidence and then make minimum necessary fixes. After the fix is complete, the main session dispatches analysis and code diffs to the read-only Reviewer. Reviewer checks:
- Does the root cause match the Zen Tao phenomenon and acceptance point?
- Is the modification scope too large?
- Are similar entrances or boundary states missing?
- Is there any obvious risk of regression?
When Reviewer gives “repair required”, execute Agent bugfix-worker Back to the repair stage;
When there is insufficient evidence, ambiguous requirements, or inability to judge, the process is suspended and the user is asked for confirmation. In this way, independent review is an important pre-commit restriction rather than a cosmetic action after the MR is created.
Verification and dependency recovery
Local verification reads first .gitlab-ci.yml It contains configuration and runs changes-related checks that can be executed locally.
If the failure clearly comes from an incomplete dependency, such as a missing node_modules、command not found or Cannot find modulethe workflow will first save the current branch, untracked file list and tracked diff temporary patch, and then execute it again:
pnpm install --frozen-lockfile
After installation, you must confirm that you are still working on the original branch and that the business diff is not lost.pnpm-lock.yaml Then rerun the original check with no additional changes to other tracked files. The process is paused when the installation fails, cannot be restored, or when repairs exceed two rounds.
MR, CI and OMP
During the submission phase, only files related to this repair will be temporarily stored. Use commit-message Generate submission and reuse dt-create-mr Create GitLab MR.
CI is not the default polling item: when the user explicitly requests query, it is queried by MR ID; it is only created when waiting, monitoring or notification are required. gitlab-mr-ci-watch heartbeat. This prevents a common fix from continuing to access external systems when the user is not authorized to do so.
OMP does not perform deployment by default. When deployment is required, it will be passed first. omp-skill Get the real environment, no guessing based on names envIdand then narrow down the candidates layer by layer according to standard product/customization, target version, customized logo, environment name and service name. Pause when environment or service name cannot be uniquely mapped.
Practice records
Distribute and install as plugin in Codex and ClaudeCode:
During actual use, we found that upstream data such as ZenTao BUG descriptions have a high impact on the success rate of problem solving.
At present, some sub-products that focus on interaction have ZenTao BUG titles as problem descriptions and the content is a gif. This combination is friendly to people, but not friendly to AI. Some text models that cannot recognize images can only pass zentao-api Skill’s text OCR is not as effective as directly reading pictures for understanding Zen Tao information.
This often requires developers to note a more detailed description of the problem from the developer’s perspective when clicking to confirm the bug based on their development experience after receiving the ZenTao BUG.
After adding more detailed context, developers can use Bugfix Agent Automatically complete a long series of subsequent operation links, and upon completion, relevant information such as the MR address and deployment environment will be provided.
Token saving optimization
Large warehouse branch directed query
When the Monorepo warehouse uses branches to distinguish sub-products, if the cumulative branches exceed thousands, there will be a large Token consumption for confirming the source branch, so use the sub-product name prefix and --list Perform queries in directed mode.
Main protocol decoupling and security downsizing
Master Clause workflow-protocol.md Once it exceeded 25 KB, the main session needed to read the document for each round of execution, sinking the underlying execution details separately.
Confirmation link supports skipping Review
The independent review environment will re-read the upstream materials and code changes to determine whether the BUG repair can be completed. Simple issues can be skipped to save time and tokens.
write at the end
Whether a Bugfix Agent is reliable does not depend on how many tools it can call, but on whether it can retry or stop at the right time, save context, avoid repeating external actions, and be able to review independently.Bugfix Agent Place these constraints at the boundaries of Skill, shared protocol, SubAgent and state script: Skill is responsible for entry and orchestration, protocol is responsible for rules, execution agent is responsible for repair, Reviewer is responsible for challenging conclusions, and state script is responsible for making the process recoverable.
When you are ready to try it based on your own actual scenario, refer to the design ideas, disassemble the atomic Skill according to your daily steps, meet the implementation position of each action, and use the main Agent as a joint to string together a whole link.
at last
Welcome to follow[Kangaroo Cloud Stack UED Team]~
The Kangaroo Cloud Stack UED team continues to share technical achievements with developers, and has successively participated in open source and welcomed stars.
