どうも、くまだです。
先に結論を書くと、置いただけだとあんまり効きません。自分も最初はフォルダ構成とか技術スタックとかを書いて満足してたんですが、実際に動きが変わったのは別のところでした。
半年くらい運用してみて、効いたものが4つあります。
1. 「やらないこと」を書く
例えば、以下のようなことを書きました。
```markdown
## 禁止事項
- gitコマンドは一切実行しない(add / commit / push すべて)
- .envファイルは絶対に読み込まない
- node_modules/ は編集しない
- 既存ファイルを削除する前に必ず確認を取る
- 指示にないファイル・ディレクトリの作成は、実行前に確認を取る
```「〜してください」より「〜しない」のほうが、はっきり守られる感じがあります。
理由はたぶんシンプルで、やってほしいことは無限にあるけど、やってほしくないことは有限だからかも?。だから書ききれる。書ききれるものは守られる。
「丁寧に実装してほしい」は無限です。どこまでやれば丁寧なのか誰も決められない。
「削除の前に確認する」は有限です。守ったか守ってないかも一目で分かる。
とくにgitと削除まわりは事故ると痛いので、最初に書いておくのをおすすめします。自分はここを書いてから、勝手にコミットされることがなくなりました。
2. 判断の優先順位を「並べる」
実装って、迷う場面のほうが多いじゃないですか。
「ここセマンティックには <section>`だけど、レイアウト的には <div>が素直だな」とか。
「この余白、カンプだと13pxだけど、他が8の倍数なんだよな」とか。
そういうときの判断軸を書いておくと、いちいち止まらずに済みます。
```markdown
## 実装の優先順位
1. 表示崩れ(ユーザーに見える問題)
2. セマンティクス・アクセシビリティ
3. 保守性
```ポイントは順番をつけることです。
「表示崩れも大事、a11yも大事、保守性も大事」と書くと、優先順位がないのと同じになります。3つとも満たせない場面でどうするかが決まらない。
迷いが生まれるのは「全部満たせないとき」なので、そこで何を捨てるかを先に決めておく。
3. 「完了」の定義を書く
これは書いてから明らかに変わりました。
```markdown
## 「完了」の定義
「動いた=完了」にしない。
表示された・ビルドが通っただけでは完了と見なさない。
数値確認(getBoundingClientRect / getComputedStyle / scrollWidth 等)
・目視確認まで含めて「完了」とする。
```書く前は「実装しました!」で返ってきて、開いてみたら微妙に崩れてる、みたいなことがあります。
これ、嘘をつかれてるわけじゃないんですよね。「完了」の基準が違うだけです。ビルドが通れば完了だと思っている相手に「完了しました」と言われても、そりゃそうなる。
なので何をもって終わりとするかを先に書く。そこまでやってくれます。
ちなみに「目視で確認して」だけだと弱くて、scrollWidth みたいな具体的な確認手段まで書いたほうが確実。判定できる形にする、という点では1つ目の話と同じです。
4. 「正はどっちか」を書く
これは案件が大きくなってくると効いてきます。
カンプから抜いた数値のメモと、実装した `_variables.scss` と、仕様書。ページ構成も、サイトマップと管理表の両方にある。
で、必ずどこかで食い違います。そのときに困るのが「どっちが正しいか誰も決めてない」状態。なので先に決めておきます。
```markdown
## 情報の正本(食い違ったときどっちを信じるか)
| 情報 | 正本 |
|---|---|
| 数値(余白・フォントサイズ・色) | coding-spec/design-values.md |
| クラス名・variant | coding-spec/class-naming-map.md |
| ページ構成・セクション | src/data/site-map.md |
→ ズレに気づいたら独自判断で進めず、実装を止めて報告すること
```最後の1行が地味に大事で、食い違いを見つけたときの行動まで書いておくと止まってくれます。書いてないと、たぶん良かれと思ってどっちかに寄せて進みます。
ここまで読んでくださりありがとうございました。