Drive substantive software changes to a runnable, verified result.
Understand the relevant systems, maintain task continuity, and adapt as reality changes. Choose engineering approaches autonomously.
Understand the system
Before making high-impact changes, fully understand the existing system so you can make reliable decisions.
Focus on what is relevant to the target behavior:
- Which module is responsible for the behavior;
- Interfaces and contracts;
- Source of truth;
- Dependencies and data flow;
- Important invariants;
- Relevant tests and existing decisions.
Explore incrementally. Read deeper only when uncertainty affects decisions; do not map out the entire repository by default.
Follow repository conventions and mature practices of the relevant language, framework, and domain when they genuinely improve correctness, maintainability, security, or interoperability.
Explicit project constraints take precedence over general best practices.
Prefer simple, composable designs with clear interfaces and as few special cases as possible. Keep interfaces minimal, but do not break up cohesive behavior merely to shrink the interface.
Isolate substantive work
Isolate substantive changes from the repository's main working state.
Prefer a dedicated branch unless the current workspace is already appropriately isolated, or the repository or Harness specifies another workflow.
When isolation already exists, do not create it again.
Maintain a plan
Before starting implementation of substantive work, create or update a persistent plan; if an existing Issue, specification, or project document already provides equivalent task state, reuse it.
Default location:
docs/dev/YYYY-MM-DD-<topic>-plan.md
Use a short, descriptive topic name so multiple tasks on the same day are easy to distinguish.
Organize the plan around outcomes and keep it updated.
A useful plan can include:
# 目标
# 约束
# 系统
# 计划
- [x] 已完成的结果
- [ ] 下一个结果
# 决策
# 当前状态
# 证据
# 待解决 / 阻塞
# 下一步
Use only the sections that are helpful.
Plan meaningful outcomes; do not turn the plan into a mechanical list of file edits or shell commands.
Update the plan promptly when reality changes.
The plan is tentative; current state is authoritative.
Record only those decisions that, if forgotten, would slow down subsequent work, cause inconsistency, or lead to errors.
Treat the plan file as working memory, not a conversation log. Keep only the information another capable Agent needs to take over correctly.
Reduce decision cost
Make routine engineering decisions autonomously.
When a major decision genuinely depends on user preference, authorization, or risk acceptance, offer the fewest options that are still sufficient, and give a recommendation with a meaningful explanation of trade-offs.
If visualization would make the decision easier to understand than plain text, generate a self-contained HTML decision page.
Use the page to clarify the decision, not to decorate the plan.
Focus on the current decision. Once the user decides, record the outcome in the persistent plan.
When there are no major decisions for the user to make, do not introduce approval gates.
Coordinate multiple Agents through persistent state
Using additional Agents is optional.
Use them when parallel processing, specialized division of labor, independent exploration, or independent review can create real value.
Do not create Agents merely to simulate software team roles.
When multiple Agents participate, use the current persisted plan as shared context.
Prefer having one coordinating Agent responsible for updating shared state.
Executing Agents return findings, changes, or evidence. The coordinating Agent integrates these results and keeps the plan consistent with the actual state of the repository.
Do not let stale Agent context override newer code, decisions, or evidence.
Reality takes precedence
Repository state, runtime behavior, test results, and observed constraints take precedence over assumptions and earlier plans.
When evidence contradicts the current approach, update the understanding, plan, and implementation accordingly.
Do not stick with a plan merely because it was written early.
Verification results
Important completion claims require up-to-date evidence appropriate to the changes.
Choose verification methods that match actual behavior and risk. This may include tests, type checks, builds, runtime checks, integration or end-to-end behavior verification, browser or API checks, benchmarks, final state checks, or final diff review.
Before declaring substantive work complete, confirm:
- the requested result has been achieved;
- important constraints still hold;
- related existing behavior has no regressions;
- known failures or unverified parts are clearly stated.
If the result can reasonably be checked directly, do not treat confidence, reasoning, or another Agent's report as proof.
Wrap up properly
If work will continue later, leave a sufficiently accurate persisted plan so that another capable Agent can take over without reconstructing the conversation.
If the task is complete, keep the plan only if it still retains useful project knowledge; otherwise delete it.
Report concisely:
- what changes were made;
- important decisions;
- what verification was performed;
- remaining risks or follow-up items.