Communitygithub.com

lguidolin/設計してから構築

新機能の開始、重要度の高いバグ修正、実装コードを書く前に使用します。これを必要とする兆候: 「シンプルだからすぐにコーディングしよう」と考える、設計が承認される前にエディタを開く、仕様や計画になっていないアイデアがある。

設計してから構築 とは?

このスキルは、AIエージェント(例: Claude Code, Cursor)がコードを書く前に、設計を明示的に行うための厳格なワークフローを定義します。**Brainstorm(ブレインストーミング)→ Spec(仕様)→ Plan(計画)→ Execute(実行)→ Record(記録)** の5段階を順に進めることで、無意識の前提や早すぎる実装による手戻りを防ぎます。特に「シンプルだから設計不要」という錯覚を戒め、小さなタスクでも設計のコストと誤りのコストを比較する判断基準を提供します。CLIツールやファイル編集の前に、ユーザーと設計の承認を得ることを強制し、単なるプロトタイプや「設計しながらコーディング」を排除します。このスキルは、開発の初期段階での質を高め、長期的な生産性向上に貢献します。

対応~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/lguidolin/agent-skills/tree/main/skills/designing-before-building

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

設計してから構築 は何をしますか?

概要

作業は5つの段階を順に進めます: Brainstorm(ブレインストーミング)→ Spec(仕様)→ Plan(計画)→ Execute(実行)→ Record(記録)。設計が明確に記述され承認されるまでは、実装を開始しません。最もシンプルなタスクこそ、検証されていない前提が最もコストを生む場です。

このルールの文言に違反することは、その精神に違反することです。 「コードを書きながら設計する」は設計ではありません。

5つの段階

  1. Brainstorm(ブレインストーミング)。意図、制約、成功基準を探ります。一度に1つの質問をしましょう。トレードオフと推奨事項を含む2~3のアプローチを提案します。設計に収束し、明示的な承認を得ます。ここではコードは書きません。
  2. Spec(仕様)。承認された設計を、日付入りのドキュメントに書き起こします。仕様書は、構築されるものの契約書です。
  3. Plan(計画)。コードに触れる前に、仕様を順序立てられたレビュー可能な実装計画に分解します。
  4. Execute(実行)。計画に沿って実装し、レビューのチェックポイントを設けます。
  5. Record(記録)。何が構築されたか、そしてなぜかを、決定記録にまとめます(recording-decisions を参照)。

大規模な作業は分解してください。 リクエストが複数の独立したサブシステムにまたがる場合は、詳細を詰める前に停止して分解します。各サブプロジェクトは独自のサイクルを実行し、依存関係の順序に従って構築します。

使用すべきでない場合

真に些細で元に戻せる編集(タイプミス、ログ行、設定値)は、Execute(実行)段階に直接進みます。判断基準: ここで間違った推測をした場合、設計ステップよりもコストがかかるか? もし「はい」なら、最初に設計を行います。

よくある正当化

言い訳現実
「これは設計が必要ないほどシンプルだ」シンプルなタスクには前提が隠れています。数行の設計は安価ですが、書き直しはそうではありません。
「進めながら設計する」設計が確定する前に書かれたコードは、書き直されるコードです。設計は独立した行為です。
「ユーザーが何を作るか教えてくれた、それが設計だ」リクエストは何を示すもので、どのようにを示すものではありません。どのようにが設計です。
「まずコードベースを調べればアプローチがわかる」調査は設計に情報を与えますが、設計の承認に代わるものではありません。
「急いでいる」急いでいる時こそ、設計を省略すると無駄な作業が発生します。

レッドフラグ — 停止

  • 承認された設計がないままエディタを開く
  • 「とりあえずプロトタイプを作ってみよう」(仕様のないプロトタイプは、レビューされていないスコープです)
  • 計画なしで複数ファイルの変更を開始する
  • ユーザーの1行のリクエストを完成した仕様として扱う

これらはすべて、停止し、設計し、承認を得てから構築することを意味します。

完全な根拠: 憲法第1条、engineering-constitution/references/engineering-constitution.md にバンドルされています。

Individual skills in this repo

This repo contains 18 individual skills — each has its own dedicated page.

lguidolin/change-hygiene-and-code-craft

Use when writing or refactoring code, structuring a commit or PR, or deciding whether to abstract duplication. Symptoms — mixing reorg with logic changes, a PR doing several things at once, a file growing large, the second copy of similar code, or unsure whether to DRY something up.

lguidolin/cloud-delivery-aks

Use when deploying to Kubernetes or Azure Kubernetes Service (AKS), configuring cloud secrets, setting up progressive rollout/canary, per-PR ephemeral environments, or k8s health probes. Keywords — Kubernetes, AKS, Key Vault, Argo Rollouts, Flagger, canary, blue-green, liveness, readiness, PodDisruptionBudget, HPA, rollback, GHCR.

lguidolin/commit-history-rewrite

Use when an existing repository has messy commit history that needs to conform to conventional commits before adopting release-please, or when intermediate WIP/fixup/merge commits need to be cleaned up.

lguidolin/conventional-commits-and-releases

Use when committing, writing a commit message, opening a PR that will be squash-merged, or configuring automated versioning/changelogs. Keywords — conventional commits, release-please, semver, feat/fix/chore, breaking change, changelog.

lguidolin/defense-in-depth-security

Use when handling untrusted input, secrets, authentication/authorization, or dependencies — or threat-modeling a new surface. Keywords — STRIDE, threat model, least privilege, secrets management, supply chain, dependency scanning, input validation, audit log, defense in depth.

lguidolin/engineering-constitution

Use when starting work in a project that follows the engineering constitution, orienting to its rules, or deciding which engineering practice applies to a task — spec writing, commits, testing, security, deploys, database, or UI work.

lguidolin/graphql-contract-testing

Use when writing a GraphQL query/mutation that the UI and a test will share, or building route/schema contract or smoke tests. Symptoms — copying a query into a test, a test asserting on query text, schema change that didn't break the UI build, or RLS/permission drift. Keywords — graphql-codegen, typed document, contract test, route smoke test.

lguidolin/init-repo-CI

Use when setting up a new repository with conventional commits, release-please, and CI automation, or when retrofitting an existing repository that lacks automated versioning and PR validation workflows.

lguidolin/interface-craft-and-accessibility

Use when building or styling UI — components, layouts, forms, design tokens — or making accessibility decisions. Keywords — a11y, WCAG, keyboard navigation, focus state, contrast, design system, minimalist UI, component reuse, ARIA, semantic HTML.

lguidolin/merge-gates-and-automation

Use when setting up or changing CI, pre-push hooks, or a task runner, or deciding what must pass before merge. Symptoms — tempted to put authoritative checks only in a local hook, skip CI, bypass with --no-verify, or unsure what gates a merge vs. runs locally.

lguidolin/observability-and-slos

Use when adding logging, metrics, tracing, health checks, SLOs, or alerting — or when building a service surface that needs to be operable and debuggable. Keywords — structured logs, OpenTelemetry, correlation id, RED metrics, liveness, readiness, SLI, SLO, error budget, alerting.

lguidolin/performance-and-scale

Use when working on hot paths, list endpoints, pagination, data-access in loops, or public interfaces/schemas. Symptoms — unbounded queries, N+1 access, no latency budget, optimizing without measuring, or changing an interface many consumers depend on. Keywords — pagination, N+1, Hyrum's Law, performance budget, bundle size.

lguidolin/postgres-postgraphile-rls-and-sql

Use when writing PostgreSQL, PostGraphile config, Row-Level Security policies, SQL schema files, or working on the Browser→App→PostGraphile→Postgres data path. Keywords — RLS, SECURITY DEFINER, search_path, pgSettings, grants, roles, GraphQL depth limit, query cost, statement_timeout, SQL file organization.

lguidolin/recording-decisions

Use when a design or architecture decision has been made and needs to be captured — writing a decision record or ADR, updating a decision index, noting a deferred idea, or superseding a past decision. Keywords — ADR, decision record, rationale, rejected alternatives, dependency index.

lguidolin/resilience-and-deploy-safety

Use when planning a deploy, designing a rollback, or responding to an incident or writing a postmortem. Keywords — deploy safety, rollback, immutable artifact, progressive delivery, canary, blast radius, incident response, blameless postmortem, error budget.

lguidolin/ship-it

Use when the user wants to ship work — push, PR, archive decision records, merge, and clean up. Handles the full lifecycle from committing final changes through post-merge cleanup including converting specs/plans to compact decision records.

lguidolin/tests-as-a-control

Use when writing or modifying tests, when a test breaks during a refactor, or when testing permission/role rules. Symptoms — tempted to edit a test to make it pass, testing only the happy path, a deny-test that started passing, flaky tests, or unsure what to assert.

lguidolin/zero-downtime-migrations

Use when changing a database schema where data must survive the change — adding/removing/renaming columns, constraints, indexes, or backfilling. Symptoms — a destructive migration bundled with a code deploy, a NOT NULL column with a backfill, a table-locking UPDATE, or a rename. Keywords — expand/contract, parallel change, backfill, NOT VALID, CREATE INDEX CONCURRENTLY, graphile-migrate.

関連スキル