harness-deepseek-harness
AGENTS.md2 starsChanged 40 days agoMITView on GitHub
HDSH packages governance gates for the Python ecosystem: GitHub issue/PR policy, bilingual documentation pairing, and pull-request workflow tooling. External projects consume the gates through prek by pointing at .pre-commit-hooks.yaml; this repository uses the same hooks it ships. Runtime code lives in src/hdsh/ with tests mirroring it in tests/; README.md introduces the product surface. Read docs/architecture.md before changing src/hdsh/; follow docs/AGENTS.md for documentation. If a required git, uv, build, test, or gate command fails because the sandbox blocks credentials, network, IPC,…
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository13 other files it gives its agents.
- .agents/rfcs/AGENTS.mdAGENTS.md
- .agents/rfcs/archived/AGENTS.mdAGENTS.md
- .agents/rfcs/implemented/AGENTS.mdAGENTS.md
- docs/AGENTS.mdAGENTS.md
- archiving-rfcsSkill
- documentingSkill
- editing-proseSkill
- finding-simplificationsSkill
- merging-stacked-prsSkill
- pushingSkill
- reviewingSkill
- translating-docsSkill
- trimming-cot-leakageSkill
The file
We split this AGENTS.md into the rules it gives an agent
6 rules. About 0 are common, 4 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- could be automatic: a setting could enforce it
- Very specific: line 34
If a required git, uv, build, test, or gate command fails because the sandbox blocks credentials, network, IPC, watching, or nested …
- Very specific: line 38
Run checks before pushes via pushing.
- Distinctive: line 41
Never default to the full suite or repeat a passing check for commit or push.
- Distinctive: line 52
Prefer maintained dependencies over hand-rolling: when they genuinely delete owned code and tests.
- Distinctive: line 57
Trust types at same-process boundaries: Do not add runtime validation, fallback behavior, or hostile-input tests solely for values the …
- Distinctive: line 59
Keep comments local: Do not restate code, explain distant behavior unless locally required, or expand unrelated comments.
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
AGENTS.md
HDSH packages governance gates for the Python ecosystem: GitHub issue/PR policy, bilingual documentation pairing, and pull-request workflow tooling. External projects consume the gates through prek by pointing at .pre-commit-hooks.yaml; this repository uses the same hooks it ships. Runtime code lives in src/hdsh/ with tests mirroring it in tests/; README.md introduces the product surface. Read docs/architecture.md before changing src/hdsh/; follow docs/AGENTS.md for documentation.
Commands
uv sync # create the environment from uv.lock
uv run pytest # tests; 100% branch coverage enforced
uv run ruff check . # lint (ALL rules minus documented conflicts)
uv run ruff format . # format
uv run basedpyright # primary type check (typeCheckingMode all)
uv run ty check # secondary type check
uv run hdsh pairing verify # bilingual pairing gate over the corpus
uv run hdsh pairing list # pairing state per document; never fails
uv run hdsh pairing record <pair> # re-record one confirmed pair
uv run hdsh pairing brief # minimal-update briefing for out-of-sync pairs
uv run hdsh rfc verify # RFC format gate
uv run hdsh rfc archive # frozen RFC archive gate
uv run hdsh rfc seal # append seals for newly archived triplets
uv run hdsh docs wrap # one physical line per prose paragraph
uv run hdsh docs links # relative links and #fragment anchors resolve
uv run hdsh docs budgets # standing-doc word ceilings (--list reports usage)
uv run hdsh scope --base <ref> # committed + worktree scope of a change
uv run hdsh worktree install # worktree-local prek hooks and merge driver
uv run hdsh adopt plan <params> # preflight a consumer adoption (see ADOPT.md)
uv run hdsh adopt apply <params> # install the harness into a consumer repository
uv run hdsh adopt verify # consumer-side drift and placeholder check
uv run prek run --all-files # every hook over the whole treeHost sandbox failures
If a required git, uv, build, test, or gate command fails because the sandbox blocks credentials, network, IPC, watching, or nested sandboxing, retry unchanged with the narrowest host escalation. Require sandbox evidence; never bypass test failures or the gates themselves.
Run relevant checks locally
Run checks before pushes via pushing; report only commands run. After gh stack sync, validate immediately; do not merge before checks pass.
- Match evidence to the surface: focused pytest tests for behavior, the pairing gate for documentation pairs, the RFC format gate for RFCs, basedpyright for type surfaces.
- Never default to the full suite or repeat a passing check for commit or push. CI owns exhaustive coverage and the platform matrix; rehearse all locally only by explicit request, for CI diagnosis, or for an irreducibly repository-wide change.
- The coverage gate is pytest itself:
fail_under=100sits inpyproject.toml, so everyuv run pytestrun enforces it.
Secrets
Tests never need real credentials; no live API is reachable from this repository. Never commit credentials or environment files.
Conventions
- Python >= 3.12, src layout: runtime code in
src/hdsh/, tests intests/mirroring it. - English is the working language for code, commits, and reviews; in-scope documents are English + Simplified Chinese pairs under the pairing contract.
- Prefer maintained dependencies over hand-rolling when they genuinely delete owned code and tests.
- Explicit > implicit at boundaries: defaulting is an explicit resolution step in the owning implementation, never a hidden
or defaultinsiderun(). - No hardcoded tunables in gates: deployment-varying choices are validated config fields changeable by the consuming repository; a
DEFAULT_*constant or test hook is not configurability. Protocol constants, external specs, and security invariants stay fixed. - Misconfiguration fails loud at load when self-contained, otherwise at the earliest resolvable point; never silently skip a missing referent.
- Opaque cross-boundary ids are typed (
NewType), never barestr. - Trust types at same-process boundaries. Do not add runtime validation, fallback behavior, or hostile-input tests solely for values the static interface requires; validate at config, parser, subprocess, file, and wire boundaries.
- An empty
exceptnames what it swallows and why nothing else can reach it; keep thetryto one statement. - Keep comments local. Do not restate code, explain distant behavior unless locally required, or expand unrelated comments.
- Prefer symmetry for parallel values; unexplained asymmetry usually signals a missed extraction.
- Tests describe behavior, not correctness. Change obsolete behavior with its tests; explain why in the PR.
- Non-trivial changes MUST include an RFC in
.agents/rfcs/in the same PR (rules); only mechanical, local edits are exempt. - Labels: one PR
kind/*, all materialarea/*, a classified Issue — native Type on organization accounts,type/*label on user accounts;source/*is Issue-only (policy). - Choose PR history deliberately. Split independent changes and fix the introducing PR before propagation; follow the workflows in .agents/skills/ for stacked branches,
--force-with-leasepushes, and checkpoint handling. - Wire mechanically checkable invariants into an executed top-level gate and prove each changed acceptance path rejects an invalid case.
- TODO markers:
FIXME/TODO/XXXby urgency (semantics). - Files end with exactly one trailing newline.
- Strictest tool defaults — ruff
ALL, basedpyrightall, coverage 100; every relaxation requires an accepted RFC in.agents/rfcs/first.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

