Skip to content
NicoVIIIPublic

About

How a kind of work is done in my repositories

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Standards

How a kind of work is done in NicoVIII's repositories, wherever that kind of work comes up. Each file covers one condition — a kind of software, an aspect of the work — and opens by stating it. They are written for people to re-read and revise, and for coding agents to be steered by.

In every repository:

  • architecture.md — module structure, domain types, boundaries, error handling
  • code-style.md — reuse, failures, the shape of functions and files, comments
  • testing.md — which tests exist, what they assert, where they live
  • commit-messages.md — what a commit message explains, and the prefixes it does not use
  • repo-setup.md — task runner, hooks, CI, devcontainer, dependency updates, releases
  • documentation.md — where knowledge is written down, and what a decision record holds

Only in a repository that fits:

  • github.md — hosted on GitHub: issues, labels, relations, milestones
  • server-backend.md — has a server backend: its contexts, use cases, contract, schema, migrations

Using them in a repository

Nothing here loads by itself. A repository takes this one in as a git submodule at docs/standards/, and its AGENTS.md lists the standards that apply to it, each with the work it is read before. The list opens by saying that a task usually falls under several standards and that every one whose work it includes is read before starting: a session otherwise reads the one its task names most narrowly and stops. Where that folder is empty, git submodule update --init fills it.

What a repository does differently is stated in its own AGENTS.md, never in a changed copy of a standard.

Writing a standard

Checking a change, and what is known about how sessions find a standard, is in CONTRIBUTING.md.

  • A rule states what to do. Keep a purpose clause only where the rule would be misapplied without it.
  • Rationale goes in a decision record, linked from the rule.
  • State the rule without an example unless it cannot be stated otherwise: an example gets read as the rule's scope.
  • Write only what departs from what a capable reader does unprompted.
  • Each rule has one home. Don't restate another standard.
  • A rule that is not settled goes under a heading that says so, phrased as a trade-off to raise, not a choice to make.
  • No reference only the maintainer can resolve.
  • A standard depends on no project: no link into one, and no rule that needs one to be understood. Projects point here, never the other way.

Decision records

A rule's record follows documentation.md, which says when a decision gets one, what it holds, and where it lives. Most rules get none.

About

How a kind of work is done in my repositories

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors