Skip to content

AGENTS.md

Latest commit

 

History

History
135 lines (104 loc) · 9.84 KB

AGENTS.md

File metadata and controls

135 lines (104 loc) · 9.84 KB

Repository Guidelines

This handbook defines how automation agents collaborate safely and effectively on the TrainLCD mobile application. Follow these instructions for every bot- or AI-assisted contribution, regardless of scope.

Operating Principles for Automation Agents

  • Honor instruction priority: repository owners & maintainers → latest task prompt → this handbook → other documentation. Surface conflicting requirements immediately.
  • Preserve the working tree: operate on the current snapshot, never discard user changes, and avoid destructive commands (git reset --hard, git clean -fd, etc.).
  • Favor minimal, auditable diffs: prefer additive edits, keep formatting deterministic, and annotate non-obvious changes with concise comments.
  • Document reproducibility: record every manual command you execute and note any local assumptions about environment variables or credentials.
  • Validate assumptions proactively: confirm tool versions, workflow expectations, and environment needs instead of relying on cached knowledge.
  • Clarify uncertainty: request guidance or leave TODO notes rather than guessing at intent.
  • Prioritize quality and performance over speed: prefer well-structured, performant implementations over quick solutions. Take extra time to consider edge cases, optimize hot paths, and ensure code correctness rather than rushing to deliver.

Standard Workflow

  1. Intake: read the full issue, PR discussion, or prompt; restate deliverables and constraints before coding.
  2. Reconnaissance: map relevant files with rg, ls, or find; review interfaces and existing patterns to plan compatible changes.
  3. Plan: outline discrete steps, keep the plan updated as you progress, and expose blockers early.
  4. Implement: use apply_patch for targeted edits, commit in small logical units, and avoid regenerating large files unless required.
  5. Validate: run only the necessary commands (npm run lint, npm test, npm run typecheck, etc.) and capture summarized output.
  6. Document & Handoff: update READMEs or docs when behavior changes, summarize modifications, list executed commands, and attach artifacts (logs, screenshots) before opening PRs.

Repository Map

  • src/: Expo React Native app code.
    • src/components/, src/screens/: UI components and screen containers.
    • src/hooks/, src/store/, src/stacks/: shared state, navigation, and composition hooks.
    • src/lib/, src/providers/, src/config/: integrations, context providers, configuration utilities.
    • src/constants/, src/utils/, src/translation.ts, src/lineSymbolImage.ts: constants, helpers, localization maps, and asset selectors.
    • @types/, src/__mocks__/, src/__fixtures__/, test/: global typings, reusable mocks, fixtures, and test helpers.
  • assets/: static media (images, fonts, icons).
  • docs/: human-facing documentation including changelog and incident notes.
  • utils/: developer tooling scripts such as GraphQL codegen config.
  • android/, ios/: native projects.
  • functions/: Firebase Cloud Functions.

Tooling & Environment Expectations

  • Target Node.js 22.x and npm 10.x.
  • Run npm install when dependencies shift; avoid re-locking packages unless instructed.
  • Metro cache issues: run expo start --clear only when debugging build failures and document the action.
  • For native builds, rely on project scripts (npm run android, npm run ios).
  • GraphQL codegen requires GQL_API_URL in .env.local; run npm run gql:codegen after document or schema updates.

Build, Test & Development Commands

  • npm run start: start the Expo Dev Client locally.
  • npm run android / npm run ios: build native binaries.
  • npm run web: run the web preview.
  • npm run lint: execute Biome linting (biome ci ./src in CI).
  • npm run format: apply Biome formatting fixes.
  • npm test: run Jest in UTC; add --watch or --runInBand for debugging.
  • npm test -- --updateSnapshot: refresh Jest snapshots when output diffs are intentional.
  • npm run typecheck: enforce TypeScript constraints.
  • npm run gql:codegen: regenerate generated GraphQL types.

Coding Style & Naming Conventions

  • .editorconfig enforces UTF-8, two-space indentation, single quotes, and ES5 trailing commas.
  • Biome is authoritative; avoid // biome-ignore unless a rule is truly incompatible and document the rationale inline.
  • Components → PascalCase (StationBanner.tsx); hooks → use* (useStationFeed.ts); Jotai atoms → store/atoms/*.ts; GraphQL operations → FeatureVerbQuery.
  • Co-locate style modules or constants near their consumers; share cross-cutting utilities through src/utils/.
  • Keep comments purposeful: explain intent or non-obvious constraints, not obvious mechanics.

Markdown documentation (docs/, README, .claude/skills/**/SKILL.md)

markdownlint-cli2 準拠。CodeRabbit も同ルールで指摘するため、執筆時点で以下を守る:

  • MD040 (fenced code language): フェンスコードブロックには必ず言語指定を付ける。用途別の既定: 平文の図示・実行計画サマリは text、シェル例は bash、差分は diff、埋め込みテンプレ本文は markdown、構造化データは json / yaml。
  • MD038 (no spaces in code spans): インラインコード（バッククォート）の内側先頭・末尾に空白を入れない。`**v<release_version>**` は OK、`**v<release_version>** ` は NG。
  • MD031 / MD032 (blanks around fences / lists): フェンスコードブロック・リストブロックの前後に空行を 1 行入れる。
  • MD029 (ordered list numbering): 順序リストの番号付けは単一ファイル内で統一する（全て 1. で書くか、1. 2. 3. と逐次番号を振るか）。
  • MD033 (inline HTML): Markdown で表現できる構造は HTML タグに落とさない。例外として <details><summary>…</summary> と表セル内の <br> は許可。

Testing Strategy

  • Jest global setup lives in jest.setup.js and src/setupTests.ts.
  • Co-locate unit tests as .test.ts or .test.tsx siblings to the module.
  • Reuse helper utilities from src/utils/test/ to avoid duplicate setup code.
  • Mock network and Firebase layers with jest.mock, and call jest.clearAllMocks() in afterEach.
  • For integration flows, extend src/test/e2e.ts and prefer fixtures from src/__fixtures__/.
  • When modifying behavior, update or add tests in the same change set; document skipped tests with TODOs and owner rationale.

Commit & Pull Request Protocol

  • Commit messages must be single-sentence statements in Japanese (e.g., テレメトリー送信機をリファクタリングしてnull状態を回避); prefix production hot fixes with Hotfix:.
  • Keep commits logically scoped (implementation, tests, docs) and mention generated artifacts in the description.
  • Pull requests must follow .github/pull_request_template.md; do not add or remove sections from the template without maintainer approval.
  • Pull requests must be assigned to @TinyKitten.
  • Pull requests must include:
    • Purpose and summary of key changes.
    • Regression risk assessment and mitigation.
    • Commands executed locally (e.g., npm run lint && npm test && npm run typecheck).
    • Linked issues or tickets.
    • Screenshots or recordings for UI/UX deltas with device names (e.g., Pixel 8, iPhone 15 Pro).
  • If CI fails, pause reviews until you add root-cause notes plus reproduction steps or open an issue for blocking infrastructure problems.
  • Keep PR metadata in sync with the branch state. Whenever you push new commits to an open PR, refresh both the PR title and the body:
    • Title: re-evaluate whether the current title still describes the full scope of the branch. If new commits introduce a subject that the title does not cover, propose an updated title and, once approved by the user, apply it via gh pr edit --title.
    • Body: update the 変更の種類 checkboxes, the 変更内容 summary, and the test-result section so they reflect the updated diff. Preserve human-authored prose sections (概要, narrative added under 変更内容, 関連Issue, スクリーンショット) unless the changes invalidate them.

Security & Configuration Guardrails

  • Store secrets in .env.local; treat .env as the template, and keep .env.example synchronized for onboarding.
  • Never commit credentials, access tokens, or production endpoints.
  • Protect Expo credentials with 2FA and rotate access when automations change.
  • After dependency upgrades (npm update) or Expo SDK migrations, run expo-doctor, npm run lint, npm test, and npm run typecheck, then capture results in docs/changelog.md.

Automation Checklists

Before submitting code changes

  • Confirm requirements and flag conflicts.
  • Update or add tests relevant to code changes.
  • Run npm run lint, npm test, and npm run typecheck; record summaries.
  • Update documentation (README, docs/, inline comments) if behaviors shift.
  • Capture screenshots/video for UI changes with device labels.

For documentation-only tasks

  • Ensure docs match current directory structure and script names.
  • Update cross-references (README, docs/) to prevent drift.
  • Spell-check or self-review for clarity and typos.

For workflow, release, or CI updates

  • Cross-check .github/workflows/ for consistency.
  • Provide dry-run instructions or environment prerequisites.
  • Document required secrets, environment variables, or service accounts.

Communication & Incident Reporting

  • Surface blockers or ambiguities in the task thread; do not proceed on assumptions.
  • When discovering regressions or flaky tests, open an issue with reproduction steps and assign the relevant code owner.
  • After incidents or hot fixes, append learnings to docs/changelog.md and notify maintainers for follow-up.