Skip to content
DCoding logo DCoding Documentation

Reference AGENTS.md File

This AGENTS.md file should be used as a reference, it should not be used ‘as-is’ in every projects hosted under the DCoding Labs Github organization. Different projects will, unavoidably, have different priorities, technical goals, and organizational scar tissues. So, every project maintainer should spend some time thinking about what that project’s AGENTS.md file should include. The purpose of this reference file is to prevent arbitrary differences within our projects.

  • Be concise, direct, and pragmatic.
  • Challenge weak assumptions instead of silently accepting them.
  • Prefer minimal diffs and ask before risky changes.
  • Avoid refactoring unrelated code.
  • Ask before making code changes unless the user is clearly asking for implementation.
  • Do not make commits unless explicitly asked.
  • Do not install dependencies or update lockfiles without asking first.
  • Do not change CI, build tooling, or project configuration without asking first.
  • Don’t read .env* or secrets files unless explicitly requested.

Code style

  • Prefer simple code over abstraction.
  • Try not to introduce unnecessary indirection.
  • Prefer inlining over splitting code into extra functions or methods, unless the extracted code is pure or reused more than once.
  • Use type hints when possible.
  • Prefer single-word variable names when possible, but do not use cryptic or overly short names to sacrifice readability.
  • Write comments only when explaining non-obvious behavior or necessary context.
  • Use empty lines to separate logical parts of the code, but do not overdo it.

Verification

  • Run cheap relevant tests even for small changes.
  • Always run relevant tests for bigger changes.
  • Explicitly tell the user when tests were run.

Communication

  • Do not narrate obvious steps.
  • For reviews, focus on bugs, regressions, risks, and missing verification more than style issues.

Git

Use the Conventional Commits format for every commit message:

<type>[optional scope]: <short description>


[optional body]


[optional footer(s)]

Rules:

  • Use feat for a new feature.
  • Use fix for a bug fix.
  • Use docs for documentation changes.
  • Use refactor for a change that alters code structure or organization, but doesn’t change behavior.
  • Use ci for changes to GitHub workflows and other systems used for CI/CD.
  • Use test when adding or updating existing tests.
  • Use build when updating the build system.
  • Use perf when improving performance
  • Use impr for user-facing improvements to existing features that aren’t bug fixes or new features.
  • Use chore for changes that don’t fit any of the other commit/change types.
  • Keep the description short and imperative.
  • Add a scope in parentheses when it helps clarify what changed, for example feat(api): add batch endpoint.
  • Add a body when extra context is useful.
  • Add footers for metadata such as issue references.
  • Mark breaking changes either by adding ! before the colon, like feat(api)!: remove v1 endpoints, or with a footer starting with BREAKING CHANGE:.
  • Agents MUST NOT create or push merge commits on main. If main has advanced, rebase local commits onto the latest origin/main before pushing.
  • Messages should, at most, contain 72 characters.
  • Before committing, confirm the commit type (feat, fix, refactor, etc.) and scope with the user. Do not assume.
  • Branch names should use the same type prefix as commits: feat/, fix/, docs/, refactor/, ci/, test/, build/, perf/, impr/, or chore/.
  • Do not include a scope in branch names. Scopes belong in commit messages only (e.g., use impr/image-modal-refinements, not impr/ui/image-modal-refinements).

GitHub

  • Pull request titles should follow the Conventional Commits format just like commit messages do.
  • Only humans can merge pull requests. Agents MUST NOT merge PRs.
  • Always check .github/pull_request_template.md before creating a PR and use it for the description.
  • Before creating a PR, run npm run lint:check and npm run format:check (backend) and npm --prefix src/FE run lint:check and npm --prefix src/FE run format:check (frontend). Fix any issues before pushing.

Markdown Style

  • Keep all lines in markdown files to a maximum of 100 characters.
  • Use * instead of - for bullet point lists.
  • Always add a blank line between a heading and the paragraph that follows it.
  • One blank line before and after code blocks.
  • Consistent column padding in tables.
  • No skipping heading levels (e.g., jumping from H2 to H4).