Codex
2a8f279575
Also records instruction hygiene, YAML-first config split guidance, and Sub2API D601 recovery notes from the recovered worktree state.
84 lines
5.7 KiB
Markdown
84 lines
5.7 KiB
Markdown
# 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`.
|