Skip to content

AGENTS.md

Latest commit

 

History

History
27 lines (25 loc) · 4.42 KB

AGENTS.md

File metadata and controls

27 lines (25 loc) · 4.42 KB

AGENT DIRECTIVES

General

  • Never use any or as unknown as
  • Never use nested ternary expressions. Use if/else, a helper function, or named intermediate values instead.
  • Never use === true, === false, etc. in boolean conditions; keep them as terse and simple as possible like !condition. Extract conditions to variables when the variable name adds clarity/insight into the reason for the condition.
  • In boolean condition contexts, use the shortest syntactically equivalent expression. Prefer items.length over items.length > 0, !items.length over items.length === 0, and items?.length over items && items.length > 0.
  • Always consider the impact of a change on tests or when more test cases are needed. Never make tests pass for the sake of passing; always exercise real behavior.
  • Always keep documentation updated and accurate while being minimal and concise.
  • Keep paragraphs to no more than 3 concise sentences. Prefer bullets for dense details.
  • Keep README.md as the landing page and docs index. Do not turn it back into the only canonical reference for every example and workflow.
  • When public-facing install, runtime, CLI, library API, agent workflow, or release guidance changes, update the relevant canonical docs in the same change: README.md, docs/installation.md, docs/cli.md, docs/library-api.md, docs/agent-workflows.md, docs/how-it-works.md, and PUBLISHING.md as applicable.
  • For repo-understanding flows, start with node ./dist/cli.js doctor and node ./dist/cli.js orient --root . --budget small --json when dist is built; build first if validating the working tree from a fresh checkout.
  • For source-checkout validation and contributor examples, prefer node ./dist/cli.js ...; reserve bare codegraph ... for published/global install guidance.
  • Treat --root as the project boundary for config lookup, cache/manifests, path confinement, and output normalization. When --root is set, positional paths are include roots; for orient and drift, positional paths are always include roots.
  • Keep discovery glob guidance accurate: codegraph.config.json globs are project-root-relative, while CLI --include-glob/--ignore-glob values are one-off filters relative to each active scan root.
  • Within any claimed cross-language capability, behavior should stay consistent across all supported languages for that capability. Avoid language-subset branches; if a limitation is intentional, document it in the parity docs and cover it with explicit tests in the same change.
  • When language support changes, update docs/language-parity.md and docs/scenario-catalog.md in the same change so support claims, limitations, and fixture coverage stay aligned.
  • When adding or changing a cross-file language scenario, add or update the nearest language test in tests/languages/*.test.ts and the shared semantic coverage in tests/goto.test.ts, tests/references.test.ts, and tests/native-semantic-parity.test.ts when the language uses the native runtime.
  • Always keep the README.md table of contents updated whenever README sections are added, removed, or renamed.
  • When CLI commands, flags, or output contracts change, update both docs/cli.md and codegraph-skill/codegraph/SKILL.md in the same change.
  • Always keep codegraph-skill/codegraph/SKILL.md updated when CLI commands, flags, or capabilities change. This file is the skill definition used by agents and must reflect the current tool surface.
  • Before major commits or concluding work, run npm run check to verify formatting, lint, build, and tests together. During iteration, use the narrowest meaningful test command: targeted Vitest suites for localized changes, npm run test:fast for broader TypeScript changes, npm run test:integration for CLI/report/output contracts, and npm run test:native when touching packages/codegraph-native.
  • Installation guidance must use @lzehrung/codegraph and the @lzehrung GitHub Packages registry. Keep detailed install docs in docs/installation.md.
  • Any persistent storage schema change (e.g. SQLite tables/columns/indexes) MUST include a migration path for existing on-disk data. If using CREATE TABLE IF NOT EXISTS, you must also ALTER TABLE / backfill as needed (or introduce explicit schema versioning) and add a regression test that starts from an older schema to prove upgrades work.
  • DO NOT use curly quote variants or other non-standard characters humans would not type with a standard QWERTY keyboard.