pikasTech-unidesk/docs/reference/agent-instruction-hygiene.md

Agent Instruction Hygiene

This document is the long-term reference for keeping always-loaded agent instruction files small, navigable and stable. It applies to local and remote AGENTS.md, CLAUDE.md-style aliases and any repo-level instruction file that is automatically injected into an agent context.

Size Budget

AGENTS.md is an index, not a knowledge base. The hard size budget for any local or remote AGENTS.md is 10 KiB, measured as bytes with wc -c AGENTS.md.

When an AGENTS.md is already over 10 KiB, do not append more detailed rules to it. Split first, then add only a one-line index entry back to AGENTS.md.

When editing an AGENTS.md would push it over 10 KiB, route the new content to a skill or a docs/reference/*.md document and keep AGENTS.md as a short pointer.

If loading or printing AGENTS.md triggers CLI output dump or context blow-up, treat that as a visibility bug and an instruction-hygiene bug. The fix is to split the file, not to increase output limits or ask agents to read around the dump.

What Belongs In AGENTS.md

Keep only always-needed routing information in AGENTS.md:

• Project identity and source-of-truth boundaries.
• P0 one-line rules that prevent immediate damage.
• Links to the authoritative long-term reference document for each domain.
• Skill names that must be loaded for common workflows.
• Short warnings about secrets, destructive commands, target workspaces and build bans.

Do not put long examples, command transcripts, JSON output, issue timelines, architecture essays, provider-specific debugging logs or one-off incident analysis in AGENTS.md.

Where Overflow Content Goes

Use this routing order when splitting content out of AGENTS.md:

• Reusable workflow behavior belongs in a skill SKILL.md, for example $dad-dev, $unidesk-cicd, $unidesk-gh, $unidesk-trans, $unidesk-otel, $unidesk-webdev or $unidesk-ymalops.
• Stable project constraints, workspace rules, architecture boundaries and validation criteria belong in docs/reference/*.md.
• CLI shape, output style, route syntax and operator ergonomics belong in docs/reference/cli.md unless a narrower reference already owns them.
• Deployment hygiene, fixed repo boundaries and source-of-truth rules belong in docs/reference/devops-hygiene.md.
• Node/lane-specific HWLAB rules belong in docs/reference/hwlab.md and the target repo's own reference docs.
• AgentRun source-truth and deployment-lane rules belong in docs/reference/agentrun.md.
• Platform-infra and YAML-first operations belong in docs/reference/platform-infra.md and docs/reference/yaml-first-ops.md.
• Process notes, temporary findings and dated investigation logs belong in GitHub issues, PR comments or process notes; they must be distilled before entering long-term reference.

If a rule is both reusable across projects and specific to UniDesk's current directories or services, put the reusable workflow in the skill and put UniDesk-specific paths, lane names and validation boundaries in docs/reference/*.md, then cross-reference both.

Split Procedure

When an agent sees a local or remote AGENTS.md over 10 KiB:

1. Identify the detailed section being changed or expanded.
2. Move the detailed content to the owning skill or docs/reference/*.md document.
3. Replace the original section with one concise bullet and a link to the authoritative location.
4. Preserve P0 damage-prevention warnings in AGENTS.md, but compress them to one-line routing rules.
5. Do not create a single giant overflow archive as the normal solution. A temporary migration note is acceptable only if it immediately points to the domain documents that must absorb it.
6. Do not add tests, guards or preflight checks just to enforce the size budget unless the user explicitly asks. The default control is documentation hygiene plus concise review.

For large legacy files, split incrementally by domain. Each new edit should leave the touched domain smaller and better referenced than before.

Cross-Reference Requirements

Every AGENTS.md index entry that points out of the file must name the authoritative target. Prefer direct paths such as docs/reference/hwlab.md or skill names such as $unidesk-cicd.

Avoid duplicated full rules between AGENTS.md, skills and long-term reference docs. AGENTS.md may summarize; the reference owns the detail. If two references conflict, update the narrower domain reference and keep only one authoritative version.

Secrets And Output Hygiene

Instruction files must not contain secrets, full API keys, full DSNs, base64 payloads, bearer tokens, SSH private keys or copy-pastable credentials.

Do not paste large CLI output, OTel trace dumps, JSON arrays or browser transcripts into AGENTS.md. If a large output demonstrates a durable rule, summarize the rule and link to the issue or reference that owns the conclusion.

Current UniDesk Routing Map

The current top-level routing map is:

• CLI behavior and output: docs/reference/cli.md.
• YAML-first configuration: docs/reference/yaml-first-ops.md and $unidesk-ymalops.
• Platform infrastructure: docs/reference/platform-infra.md and $unidesk-sub2api when Sub2API is involved.
• Distributed field repair: $dad-dev plus docs/reference/devops-hygiene.md.
• CI/CD and rollout: $unidesk-cicd plus docs/reference/cli.md.
• GitHub issue and PR writes: $unidesk-gh.
• Trans/remote patch transport: $unidesk-trans plus docs/reference/cli.md.
• Web UI, Workbench and web-probe: $unidesk-webdev.
• OpenTelemetry and Tempo: $unidesk-otel plus docs/reference/observability.md.
• HWLAB node/lane operation: docs/reference/hwlab.md.
• AgentRun: docs/reference/agentrun.md.
• Master/D601 development environment: docs/reference/dev-environment.md.
• Secretary work: docs/reference/secretary-reference.md.