|
# SYSTEMNOTE_DEVELOPMENT_RULES_V1
## 1. 文書の目的
本書は、SystemNote・PrismNote・和綴手帖を長期的に開発・保守するための共通開発ルールを定義する。
目的は以下の通り。
- 設計者の意図を正確に反映する
- 個別パッチの積み重ねを防ぐ
- 無駄な修正コストを減らす
- AI開発の速度を活かしつつ設計品質を維持する
- 将来の仕様変更に柔軟に対応できる構造を保つ
- SystemNoteシリーズ全体で命名・構造・テスト方法を統一する
- 「一生使える」製品として長期間保守できるコードを維持する
本書は、機能仕様書より上位の「開発憲法」として扱う。
---
# 2. 最重要原則
## 2.1 設計意図を最優先する
個々の修正指示をそのまま局所実装するのではなく、まず「なぜその修正が必要なのか」を理解する。
画面上の現象ではなく、設計者が実現したい状態を基準に実装する。
---
## 2.2 症状ではなく原因を直す
表示位置がずれた場合、すぐに `margin-left: 3px` や `top: -2px` などを追加しない。
最初に以下を確認する。
- 親レイアウト
- Grid / Flex構造
- padding / gap
- box-sizing
- 固定幅 / 固定高
- overflow
- 相対単位
- 共通CSS
- DOM構造
- 既存の例外処理
個別補正は最後の手段とする。
---
## 2.3 個別パッチを原則として増やさない
以下のような例外コードを安易に追加しない。
- スマホだけ
- この機能だけ
- この画面だけ
- このバージョンだけ
同じ問題が複数箇所に存在する可能性がある場合は、共通部分を修正する。
例外が必要な場合は、なぜ共通化できないのか明確な理由を持たせる。
---
## 2.4 一つの変更で複数の問題を解決する
理想的な修正は、
「スマホ予定画面の余白を直した」
ではなく、
「ページ内余白の共通ルールを直した結果、予定・日記・住所録・資産管理が全部正しくなった」
という修正である。
修正件数ではなく、構造改善の効果を重視する。
---
## 2.5 過剰設計もしない
将来使うかもしれないという理由だけで巨大な抽象化や複雑なフレームワークを作らない。
現在必要な機能を、将来変更しやすい最小構造で実装する。
「シンプルであること」を最優先する。
---
# 3. 開発時の判断順序
修正要求を受けた場合は、必ず次の順番で判断する。
```text
設計意図
↓
原因
↓
共通化できるか
↓
影響範囲
↓
最小で構造的な修正
↓
実装
↓
テスト
↓
不要コード削除
```
禁止する流れ：
```text
指示
↓
コード追加
↓
見た目が直った
↓
終了
```
---
# 4. 開発開始前に確認すること
## 4.1 今回の目的
「何を直すか」ではなく「なぜ直すのか」を最初に定義する。
悪い例：
> スマホ時の右余白を5px減らす。
良い例：
> スマホ時に用紙幅を最大限利用したい。個別px補正ではなく、全機能共通のページ余白設計として修正する。
---
## 4.2 対象範囲
修正対象を明確にする。
例：
- SystemNoteのみ
- PrismNoteのみ
- 和綴手帖のみ
- 3製品共通
- 予定機能のみ
- 全モジュール共通
- PCのみ
- スマホのみ
- 1P / 2P共通
---
## 4.3 変更禁止部分
完成済み部分を不用意に変更しない。
必要に応じて、
> 指定部分以外のデザイン・機能・データ構造は変更しない。
と明記する。
---
## 4.4 完了条件
実装前に、何をもって完成とするかを決める。
例：
- 360px～1920pxで破綻しない
- PC / スマホで操作可能
- 1P / 2Pで同じデータを表示
- 戻る操作でログイン画面へ抜けない
- 既存データを破壊しない
---
# 5. AIが最初に行うこと
コードをすぐ変更しない。
最初に既存構造を確認する。
確認対象：
- HTML構造
- CSS構造
- JavaScript構造
- 共通処理
- 製品固有処理
- データ構造
- イベント処理
- レスポンシブ処理
- 重複コード
- 過去のパッチ
- 使用されていないコード
- 命名の不統一
そのうえで、症状ではなく原因を特定する。
---
# 6. 共通化ルール
SystemNote・PrismNote・和綴手帖で、見た目以外が同じものは共通化を優先する。
共通化対象例：
- データ処理
- IndexedDB
- CRUD
- 検索
- フィルタ
- モーダル
- 人物リンク
- 人生年表
- 入力部品
- ナビゲーション
- 戻る処理
- バックアップ
- 復元
- バリデーション
- 日付処理
- 画像処理
製品差は原則として以下に限定する。
- UIテーマ
- 色
- フォント
- 余白
- 装飾
- 製品名
- 必要な表示差分
---
# 7. HTML / CSS / JavaScript の責務分離
## 7.1 HTML
HTMLは構造と意味を担当する。
レイアウト微調整のための無意味な要素を増やさない。
---
## 7.2 CSS
CSSは表示・配置・レスポンシブを担当する。
JavaScriptで位置やサイズを直接調整しない。
---
## 7.3 JavaScript
JavaScriptは動作・状態・データ連携を担当する。
見た目の調整はCSSへ委ねる。
---
# 8. CSS設計ルール
## 8.1 固定値より相対設計を優先する
用途に応じて以下を優先する。
- `rem`
- `em`
- `%`
- `fr`
- `minmax()`
- `clamp()`
- `min()`
- `max()`
`px` は罫線、細かな物理表現、最低寸法など、本当に固定する意味がある場所に限定する。
---
## 8.2 単位の基本
| 用途 | 推奨 |
|---|---|
| 基本文字 | rem |
| 文字に比例する高さ | em |
| 余白 | rem |
| ボタン | em / rem |
| 入力欄 | em / rem |
| ページ幅 | %, fr, min(), max(), clamp() |
| グリッド | minmax() |
| 画像 | %, aspect-ratio |
| ボーダー | px |
| 細い罫線 | px |
| 小さなアイコン調整 | px可 |
| 最大幅 | rem または px |
| ブレークポイント | px / rem |
---
## 8.3 固定heightを減らす
避ける：
```css
height: 40px;
```
優先：
```css
min-height: 2.5rem;
padding-block: .5rem;
```
文字量や画面幅が変わっても自然に伸びる構造を優先する。
---
## 8.4 レイアウトは流れで作る
絶対座標中心で配置しない。
以下を基本とする。
- CSS Grid
- Flexbox
- Normal flow
PC、1P、2P、スマホを別々の画面として作るのではなく、同一構造が自然に変形する設計を目指す。
---
## 8.5 個別px補正を避ける
以下のような補正を増やさない。
```css
margin-left: 7px;
top: -3px;
width: calc(100% - 14px);
```
必要な場合は、まずレイアウト構造に原因がないか確認する。
---
## 8.6 SystemNote特有の固定値
以下は一定のpx指定を許容する。
- 罫線
- ページ角丸
- リング径
- 中央溝
- ページ重なり表現
- 手帳の物理的装飾
ただし本文・ボタン・入力領域のサイズは原則相対化する。
---
# 9. 命名規則
## 9.1 基本原則
**短く、意味が分かり、同じ概念には同じ名前を使う。**
名前だけを見て役割が想像できることを優先する。
---
## 9.2 JavaScript
変数・関数は `camelCase`。
例：
```javascript
pageId
personId
entryList
activeTab
openPage()
saveEntry()
findPerson()
loadData()
```
### 操作関数
動詞＋対象。
```javascript
openPage()
closeBook()
saveDiary()
deleteEntry()
addPerson()
findPerson()
linkPerson()
```
### イベント
`on` + 対象 + 動作。
```javascript
onTabClick()
onPageOpen()
onFormSubmit()
onBack()
```
### 真偽値
`is` / `has` / `can`。
```javascript
isOpen
isMobile
hasImage
canEdit
```
---
## 9.3 定数
`UPPER_SNAKE_CASE`
```javascript
APP_VERSION
SCHEMA_VERSION
DEFAULT_THEME
MAX_IMAGES
```
---
## 9.4 CSSクラス
`kebab-case`
```css
.note-page
.page-title
.person-link
.life-timeline
.book-cover
```
状態：
```css
.is-active
.is-open
.is-hidden
.is-mobile
.is-locked
```
所有状態：
```css
.has-image
.has-link
.has-note
```
---
## 9.5 HTML ID
JavaScriptから一意に参照する必要があるものだけ使用する。
```text
#app
#book
#login
#modal
```
レイアウト目的ではIDを使わずCSSクラスを使う。
---
## 9.6 データ項目
`camelCase` で統一する。
```javascript
{
id,
title,
createdAt,
updatedAt,
personIds,
imageIds,
isFavorite
}
```
単数・複数を明確にする。
```text
personId // 1件
personIds // 複数
```
---
## 9.7 ファイル・フォルダ
小文字＋ハイフン。
```text
life-timeline.js
person-link.js
book-cover.css
data-store.js
```
機能フォルダも同じ。
```text
note/
schedule/
diary/
contacts/
assets/
album/
life-timeline/
```
---
## 9.8 禁止命名
以下を新規コードに使用しない。
```text
fix2
new3
temp
rn28
v15-title
box1
data2
final-new
patch
mobileFix
new-new
aaa
tmp2
```
バージョン番号・一時修正・座標・サイズを名前に残さない。
---
## 9.9 意味不明な短縮は禁止
禁止：
```text
p1
xx
tmp2
cfgx
dtm
abc
```
一般的で意味が明確なものは使用可能。
```text
id
db
ui
url
api
css
html
```
---
## 9.10 名前の長さ
意味が失われない最短名を採用する。
良い例：
```javascript
savePerson()
```
長すぎる例：
```javascript
savePersonInformationToDatabase()
```
短すぎる例：
```javascript
sp()
```
---
# 10. 不要コードの削除
新しい実装を追加して旧実装を残し続けない。
修正後に以下を整理する。
- 古いCSS
- 古い関数
- 使用されない変数
- 重複イベント
- 一時パッチ
- コメントアウトされた旧コード
- 未使用クラス
- 過去バージョン用コード
「動くから残す」を認めない。
---
# 11. source と dist を分離する
開発原本：
```text
src/
```
製品配布版：
```text
dist/
```
例：
```text
SystemNote/
├─ src/
│ ├─ index.html
│ ├─ css/
│ ├─ js/
│ └─ note/
│
└─ dist/
└─ index.html
```
---
## 11.1 source
sourceは正本。
以下を優先する。
- 可読性
- 保守性
- 分かりやすい命名
- 設計意図が追える
- 人間とAI双方が理解できる
---
## 11.2 dist
distは製品配布専用。
ビルド時に以下を行う。
- HTML minify
- CSS minify
- JavaScript minify
- コメント削除
- 不要コード削除
- 必要に応じてファイル統合
- 圧縮
難読化（obfuscation）は原則不要。
---
# 12. 開発基本プロンプト
今後の開発開始時には以下を基本プロンプトとして使用する。
---
## SystemNote共通開発プロンプト
あなたはSystemNoteシリーズの長期開発担当者です。
今回の修正だけを局所的に直すのではなく、既存構造を確認し、設計意図を理解したうえで修正してください。
以下を必ず守ってください。
1. 個別パッチを安易に追加しない
2. 症状ではなく原因を修正する
3. 共通化できるものは共通構造で修正する
4. 同じ処理・CSSを重複させない
5. 不要なコードを増やさない
6. 修正後に不要になった旧コードを削除する
7. CSSは固定px中心ではなく、rem / em / % / fr / minmax / clamp等の相対設計を優先する
8. 固定heightは必要最小限とし、原則min-heightを検討する
9. CSS Grid / Flexboxによる自然なレイアウトを優先する
10. JavaScript・CSS・HTMLの命名規則を統一する
11. 同じ概念に複数の名称を使用しない
12. バージョン番号・fix・temp・patch等をクラス名や関数名に残さない
13. PC / スマホ / 1P / 2Pへの影響を確認する
14. SystemNote・PrismNote・和綴手帖で共通化できる変更は共通仕様として扱う
15. sourceコードは人間とAIの双方が理解できる可読性を維持する
16. 製品配布時のみminify・圧縮する
17. データ形式・保存・バックアップをUIより重要な長期資産として扱う
18. 指示に設計上の問題がある場合は、そのまま実装せず問題点を指摘する
19. 過剰設計は避け、現在必要な最小構造で将来変更しやすくする
20. 修正完了後は必ず回帰テストを行う
最終判断基準は、
「今回動くか」ではなく、
「製品全体として正しく、次回の変更を容易にするか」
としてください。
---
# 13. 個別修正依頼テンプレート
```text
【目的】
スマホで用紙をできるだけ広く表示したい。
【対象】
全機能共通・スマホのみ。
【現象】
右側に不要な余白がある。
【希望】
個別のmargin補正ではなく、
共通ページレイアウトの構造として修正。
【変更禁止】
PC 2P表示、リング位置、タブ位置は変更しない。
【完了条件】
360 / 375 / 390 / 430pxで
横スクロールが出ず、
左右余白が自然に揃うこと。
```
---
# 14. 新機能追加時の手順
新機能をいきなり実装しない。
## 14.1 機能の目的を定義する
例：人生年表
> 人生で重要だった出来事だけを残し、後から自分の人生を振り返れるようにする。
---
## 14.2 既存機能との関係を確認する
人生年表の場合：
- 予定
- 日記
- 記念日
- アルバム
から参照する。
---
## 14.3 共通データ構造を決める
例：
```text
sourceType
sourceId
date
title
personIds
imageIds
```
---
## 14.4 UI表現をSystemNoteの世界観に合わせる
例：
```text
登録 → 人生年表に残す
お気に入り → しおり
画像アップロード → 写真を貼る
ログイン → 手帳を開く
ログアウト → 手帳を閉じる
人物カード → ○○さんのページ
```
---
# 15. テスト基本構成
テストは4段階で行う。
---
# 16. 第1段階：機能テスト
各機能について以下を確認する。
- 新規
- 編集
- 削除
- 保存
- 検索
- フィルタ
- 戻る
- ページ切替
- データ再読込
- ロック
- 再ログイン
---
# 17. 第2段階：UIテスト
## 17.1 PC
最低限：
- 1280px
- 1366px
- 1440px
- 1920px
---
## 17.2 スマホ
最低限：
- 360px
- 375px
- 390px
- 430px
---
## 17.3 タブレット
- 768px前後
- 縦
- 横
---
## 17.4 表示倍率
- 100%
- 125%
- 150%
---
# 18. 第3段階：破壊テスト
正常なサンプルデータだけを使わない。
## 18.1 長文
- 予定タイトル100文字以上
- 日記5,000～10,000文字
- 長い人物名
- 長い会社名
- 長いタグ
- 長い住所
---
## 18.2 大量データ
- 予定数千件
- 家計簿1万件
- 住所録数千件
- 写真複数枚
- 人生年表大量件数
- 人物リンク大量件数
---
## 18.3 画像
- 横長
- 縦長
- 正方形
- 大容量
- 複数画像
- 画像なし
---
# 19. 第4段階：実環境テスト
最低限：
- Windows Chrome
- Windows Edge
- Firefox
- macOS Safari
- iPhone Safari
- Android Chrome
---
# 20. スマホ特有テスト
特に以下を確認する。
- ブラウザ戻る
- スワイプ戻る
- ソフトキーボード表示
- 縦横回転
- 画面再読込
- タブ復帰
- スクロール
- safe-area
- 画像選択
- 長押し
- タップ領域
- 二重スクロール
- モーダル位置
- 入力欄がキーボードに隠れないか
- 戻るでログイン画面へ抜けないか
---
# 21. Playwright等による自動UIテスト
主要操作を自動化する。
例：
```text
ログイン
↓
予定を開く
↓
新規登録
↓
編集
↓
保存
↓
人生年表へ追加
↓
人物リンクを開く
↓
戻る
↓
TOP
↓
手帳を閉じる
```
この一連の操作を複数画面サイズで繰り返す。
---
# 22. AIによる探索型QA
固定テストだけでなく、AIに自由操作させる。
標準指示例：
> SystemNoteを壊すつもりで自由に操作してください。通常の利用ではなく、想定外の操作、連打、画面切替、戻る、再読込、長文入力、大量入力、1P/2P切替、スマホ幅変更などを行い、UI崩れ・操作不能・データ不整合・保存不具合を探してください。
AIに試させる例：
- 高速タブ切替
- 戻る連打
- 1P / 2P連続切替
- モーダル連続開閉
- 画面幅変更
- 長文入力
- 大量登録
- 再読み込み
- ロック
- 再ログイン
- 写真大量追加
- データ0件
- データ1件
- 大量件数
- スマホ縦横回転
---
# 23. 不具合報告形式
```text
不具合ID：
重要度：
発生環境：
画面サイズ：
ブラウザ：
再現手順：
期待結果：
実際の結果：
原因候補：
修正方法：
影響範囲：
修正後確認：
```
---
# 24. 不具合重要度
## A：販売不可
- データ消失
- ログイン不能
- 保存不能
- 操作不能
- スクロール不能
- 復元不能
- 起動不能
---
## B：V1で必ず修正
- 重なり
- 文字切れ
- ボタン切れ
- モーダルはみ出し
- 戻る動作異常
- 1P / 2P不整合
- スマホ主要操作不能
- 大きなレイアウト崩れ
---
## C：販売後でも可
- 1～2px程度の差
- 微妙な余白
- 軽微なアニメーション差
- 色の微調整
---
# 25. データテスト
データはUIより長く残るものとして最重要扱いする。
必ず以下を確認する。
```text
登録
↓
終了
↓
再起動
↓
データ確認
```
さらに、
```text
バックアップ
↓
全データ削除
↓
復元
↓
完全一致確認
```
まで行う。
---
# 26. 回帰テスト
一つ直したら、その画面だけを確認しない。
例：
予定画面のページ余白を直した場合、
- 日記
- 家計簿
- 住所録
- 資産
- アルバム
- 人生年表
も確認する。
共通CSS・共通JSを変更した場合は全機能確認する。
---
# 27. 修正終了時のチェック
作業終了前に必ず以下を行う。
1. 不要CSS削除
2. 不要JavaScript削除
3. 重複イベント削除
4. 古いパッチ削除
5. 使用されていないクラス確認
6. consoleエラー確認
7. 自動テスト実行
8. 主要画面確認
9. バックアップ確認
10. バージョン更新
11. 命名規則確認
12. sourceとdistの整合性確認
---
# 28. 製品版ビルド
最終製品では以下の流れとする。
```text
src
↓
テスト
↓
minify
↓
dist
↓
製品版テスト
↓
ZIP
```
重要：
**minify前だけではなく、minify後の製品版も必ずテストする。**
---
# 29. V1完成条件
SystemNote V1製品版は、以下を満たして初めて完成とする。
- Aランク不具合 0
- Bランク重大不具合 0
- PC主要ブラウザ正常
- iPhone正常
- Android正常
- 360～1920px主要表示正常
- 1P正常
- 2P正常
- 戻る操作正常
- IndexedDB正常
- バックアップ正常
- 復元正常
- 大量データ正常
- 長文入力正常
- 画像処理正常
- 人生年表正常
- 人物リンク正常
- 表紙 / ロック正常
---
# 30. 今後の開発サイクル
```text
要望
↓
設計意図確認
↓
既存構造調査
↓
原因分析
↓
共通化判断
↓
影響範囲確認
↓
実装
↓
自動テスト
↓
AI探索テスト
↓
実機テスト
↓
不要コード整理
↓
製品ビルド
↓
利用者の反応
↓
次の改善
```
---
# 31. AI開発での役割分担
## 人間
- 製品思想
- UI思想
- 優先順位
- 設計意図
- 使い勝手の判断
- 「これはおかしい」という違和感
- 商品として必要か不要かの判断
## AI
- 既存コード調査
- 構造分析
- 共通化
- 実装
- リファクタリング
- 命名統一
- 自動テスト
- 探索型テスト
- 回帰テスト
- 軽量化
- ビルド
- 不要コード削除
---
# 32. 最終原則
> 局所的に正しいコードではなく、製品全体として正しいコードを書く。
> 今動くだけではなく、次の変更が容易になる実装を選ぶ。
> 複雑さを追加して問題を解決するのではなく、構造を整えて問題そのものを減らす。
> AIに「直して」と頼むのではなく、「設計意図を守りながら最も構造的な方法で直して」と頼む。
> テストは完成後に行うものではなく、開発工程の一部とする。
> sourceは未来の開発資産、distは現在の製品。
> 一つの修正で一つの問題だけを直すのではなく、同種の問題が起きにくい構造へ改善する。
> SystemNoteは短期開発ではなく、一生使える製品として長期開発する。
---
# 33. 文書管理
文書名：
`SYSTEMNOTE_DEVELOPMENT_RULES_V1.md`
位置づけ：
- SystemNoteシリーズ共通
- 開発基本原則
- 命名規則
- AI開発プロンプト
- テスト基準
- 製品ビルド基準
今後ルールを変更する場合は、本書を正本として更新する。
| 
