Skip to content

naatin777/plugumi / .agents/skills/coding-convention

coding-convention

Verified

コード実装時の規約。外部依存・標準ライブラリ方針・可読性基準・命名(略称を使わない)など、実装前に確認すべきルールを扱う。

実装規約

コードを書く・依存を増やす前に読む。

外部依存

  • ライブラリ・パッケージを追加する前に、必ずユーザーの許可を取る。 使いたいライブラリ名・目的・代替(標準ライブラリで足りるか)を提示して確認する
  • 標準ライブラリで実現できるなら標準ライブラリを優先する(依存を最小化する方針)
  • Go設定ファイルは外部TOMLではなく encoding/json を使う(plugumi.json)

可読性

人間が読みやすいコードを優先する。

コードの意図、責務、処理の流れ、依存関係、副作用を、少ない認知負荷で理解できるようにする。

命名、関数の分割、抽象化、コメントは、その理解を助ける場合に用いる。行数の削減、関数の細分化、抽象化そのものを目的にしない。

特に、処理を理解するために複数のファイルや関数を行き来する必要がないか、暗黙の前提を推測しなければならない箇所がないかを確認する。

レビュー時の最も重要な問いはこれ。

「この実装を初めて読む開発者が、作者に質問せずに処理の意図と振る舞いを理解できるか?」

ここでいう開発者は、その言語とプロジェクトの基本概念を理解している人を想定する。何も知らない初心者にすべてを説明するコードを目指す必要はない。

PlugumiではAIがコードを書くことも多いので、AIが生成しやすいコードではなく、人間が理解・検証・修正しやすいコードを優先する。

混同しやすいもの

簡潔さ・明示性・抽象化は、いずれも読みやすさを実現するための手段であって目的ではない。短縮で意図が隠れる・細分化で処理を追いにくくなる・過剰な抽象化が認知負荷を増やす場合がある。

記述の役割

  • コードには How(どう実現するか)を書く
  • テストコードには What(何を満たすか)を書く
  • コミットログには Why(なぜ変更するか)を書く
  • コードコメントには Why not(なぜ別の方法を採らないか)を書く

コメントは日本語で書く。

命名

  • ドメイン語の切り詰め・略称を名前に使わない。reg→registration、rt→router、sess→session、fwd→forward、ep→endpoint、REPL→command loop のように、読み手が展開を推測せずに済む形にする
  • プロトコル自体の名称(HTTP・WebSocket・JSON-RPC)と、その言語の慣用的な短い変数名(Goのctx・err・レシーバ、Rustのres、catchのerror等)は対象外

プロトコル由来の値・形にはコメントで出典を添える(例: {accepted:true} は contracts/00003 の受理response)。ファイル冒頭にそのファイルがプロトコルのどの部分を担うか一言添える。

slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 196kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 192kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 192kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 192kUpdated Claude CodeCodexVerifiedInstall