開発ガイド: CI/Workflow基線・コーディング/テスト規約・既知課題と推奨アクション #995
Description
目的
PRマージ以外に、ae-framework の開発を継続するための運用基準・規約・既知課題/推奨アクションをまとめる。
CI / Workflow 基線
- verify-lite を基準に局所修正で green 化、外因は小PRに分離。
- actionlint/shellcheck 対応:
echo >> $GITHUB_OUTPUT/$GITHUB_ENVを禁止、printf+ 適切な quoting に統一。 - 重い検証（security/formal/bench 等）は label/path で opt-in、PRは軽量・高速回転。
リポジトリ / ビルド
- pnpm ワークスペース運用。root で
pnpm i→ パッケージ横断verify-liteを実行。 - TypeScript/ESLint 設定に準拠。大規模整形は避け、差分は目的最小限に。
- 依存更新は最小範囲・小PR分割。lockfile は安易に再生成しない。
コーディング規約
- 小さく刻む（≤300行目安・論点は1つ）。Conventional Commits を徹底。
- 既存の命名/配置に合わせる。余計な抽象化や大改名を避ける。
- 変更は目的範囲内のみ。周辺改善は別Issue/PR提案に分離。
テスト戦略
- 変更に最も近いレイヤでテスト（unit → integration）。
- スナップショット更新は最小限・理由をPRに明記。外部I/Oはモック/フィクスチャ使用。
- flaky は切り分け→退避/再試行/隔離を別PRで。
ドキュメント / RFC
- 仕様/挙動変更は docs/ or RFC に追記。使用法・制約・リスクを簡潔に。
- 新規CLI/設定は該当パッケージのREADMEを更新。
品質ゲート / 優先順位
- しきい値の優先:
policy > AE-IR > ae.config（ae.config はヒント）。 - コンパレータ/単位正規化（例:
>=0.9,<=200ms,90%）は共通ユーティリティで扱う（Foundation: 共通比較ユーティリティ（parse/compare/strictest）+ 単位正規化 + テスト #915 の文脈）。 - 原則: 「PR原因の赤はPR内で直す」「外因は別PR」。
セキュリティ / コンプライアンス
- SBOM/CodeQL/Dependabot 等は label で opt-in、強制は
enforce-*ラベルで段階導入。 - Actions 権限は最小。ブランチ保護は保持。
形式仕様 / 検証
- spec-validation（AE-Spec→AE-IR）を壊さない。アーティファクトは artifacts/ を参照。
- TLA+/Apalache/Alloy/Kani 等は stub/opt-in が混在。重い検証は label で起動。
可観測性 / アーティファクト
- CIコメント upsert は固定ヘッダ（例:
<!-- AE-COVERAGE-SUMMARY -->,<!-- AE-FORMAL-AGGREGATE -->）。 - レポートは既存スキーマに合わせる（新形式は後方互換）。
GitHub 運用
- CODEOWNERS 承認を尊重。対象ディレクトリの変更は早めにレビュワー指名。
- スラッシュコマンドは Issue コメントのみ（PRコメントは対象外）。
既知の技術的課題（優先度: 中）
- actionlint ルール未統一（heredoc/quoting/printf）。
- verify-lite の外因的赤（型/lint差）。
- formal/bench/security のラベルゲート整備（report-only→段階的 enforce）。
推奨の次アクション（PRマージと並行）
- 小PR: “ci: spec-validation レポート生成を actionlint-safe に”。
- 小PR: “ci: echo→printf 移行ガード（grep/スクリプト）” をwarnで導入。
- 影響小の docs PR（docs/examples: comparator + meta quickstart #973）から通し、CI整備→機能PR群（feat(utils): comparator foundation (parse/compare/strictest) with unit normalization (#915) #970/feat(qa): treat ae.config thresholds as hints; policy remains SSOT (#918) #971/feat(reports): unified top-level meta (factory + central save hook), refs #917 #968/RFC: Composite DoD policy-loader + strictest merge; comparator spec (refs #916) #969）の順で収束。