Operating Principles

Coding agents should be treated as components of the engineering system, not as autonomous replacements for engineering judgment. In Asterinas, they work best when people define the goal, scope, and acceptance criteria, while agents execute narrow tasks and produce reviewable artifacts.

Deliver Small, Verifiable Increments

Large end-to-end requests are usually less reliable than short, bounded steps. Each step should produce something that can be checked directly, such as:

• a code change;
• a test result;
• a log bundle;
• a design note;
• a structured review report.

Every step should also have a clear exit condition. Do not move to the next phase while the current phase still fails its acceptance criteria.

Prefer Specification-Driven Work for High-Risk Tasks

For system tasks such as syscall behavior and module implementation, a conversational prompt alone is usually not enough.

A more reliable sequence is:

1. Clarify the problem and collect references.
2. Write a short task brief or product requirement document.
3. Write a technical specification for behavior, invariants, and forbidden changes when the task is high risk.
4. Ask the agent to implement within that contract.

This shifts the question from “Did the model understand the task correctly?” to “Did the implementation satisfy a checkable contract?”

Prefer Evidence Over Impression

In Asterinas development, unsupported conclusions are dangerous. High-risk claims should be backed by evidence such as:

• Linux references;
• code anchors;
• logs or traces;
• focused tests;
• structured review findings.

A useful sequence is: collect evidence, form hypotheses, run targeted validation, then write a report.

Use Linux as a Semantic Reference

Linux is often the main reference for user-visible behavior, error codes, boundary cases, and subsystem responsibilities. However, Linux should not be treated as a line-by-line implementation template.

Contributors should align with Linux semantics where compatibility matters, while keeping Asterinas-specific constraints and abstractions intact. When documenting conclusions, it is helpful to distinguish between:

• a direct match with Linux behavior;
• a behavioral match through a different implementation;
• an inference that still requires confirmation.

Manage Context Actively

Long-running agent sessions drift unless critical state is written to durable artifacts. Do not keep important decisions only inside a chat transcript.

Prefer reducing context pressure instead of continually extending the same session. Practical techniques include:

• splitting independent subtasks across sub-agents;
• restoring work from compact artifacts such as AGENTS.md, prd.md, specifications, findings, and round summaries;
• maintaining a lightweight index of key files, code anchors, logs, commands, and open questions.

Persist the following information early:

• project-wide rules in AGENTS.md;
• task goals and acceptance criteria;
• specifications for risky changes;
• review findings and round summaries;
• long-running progress trackers for multi-session work.

When the session becomes noisy or inconsistent, start a new session from those artifacts instead of patching an increasingly unreliable context. Prefer summaries and indexes over copying the raw transcript forward.