jupytermind 0.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.github/skills/ai-chemistry-scientist/SKILL.md +97 -0
- package/.github/skills/ai-chemistry-scientist/manifest.json +156 -0
- package/.github/skills/ai-data-scientist/SKILL.md +330 -0
- package/.github/skills/ai-genomics-scientist/SKILL.md +98 -0
- package/.github/skills/ai-genomics-scientist/manifest.json +93 -0
- package/.github/skills/ai-materials-scientist/SKILL.md +51 -0
- package/.github/skills/ai-materials-scientist/manifest.json +58 -0
- package/.github/skills/ai-scientist/SKILL.md +69 -0
- package/.github/skills/ai-scientist/manifest.json +61 -0
- package/.github/skills/ai-structural-biology-scientist/SKILL.md +67 -0
- package/.github/skills/ai-structural-biology-scientist/manifest.json +72 -0
- package/.github/skills/japanese-prose/NOTICE.md +17 -0
- package/.github/skills/japanese-prose/SKILL.md +111 -0
- package/.github/skills/japanese-prose/references/review-workflow.md +50 -0
- package/.github/skills/japanese-prose/references/scoring.md +24 -0
- package/.github/skills/japanese-prose/references/writing-guidelines.md +60 -0
- package/.github/skills/japanese-prose/scripts/core.py +192 -0
- package/.github/skills/japanese-prose/scripts/fixtures/natural.md +5 -0
- package/.github/skills/japanese-prose/scripts/fixtures/unnatural.md +5 -0
- package/.github/skills/japanese-prose/scripts/lint.py +378 -0
- package/.github/skills/japanese-prose/scripts/outline.py +68 -0
- package/.github/skills/japanese-prose/scripts/terms.py +112 -0
- package/.github/skills/japanese-prose/scripts/test_engine.py +117 -0
- package/.github/skills/presentation-planner/SKILL.md +257 -0
- package/.github/skills/presentation-planner/assets/design-templates/data-report.yaml +97 -0
- package/.github/skills/presentation-planner/assets/design-templates/executive-proposal.yaml +92 -0
- package/.github/skills/presentation-planner/assets/design-templates/technical-briefing.yaml +96 -0
- package/.github/skills/presentation-planner/assets/scenario-templates/data-report.md +47 -0
- package/.github/skills/presentation-planner/assets/scenario-templates/executive-decision.md +43 -0
- package/.github/skills/presentation-planner/assets/scenario-templates/technical-briefing.md +45 -0
- package/.github/skills/presentation-planner/references/customizing-design-templates.md +160 -0
- package/.github/skills/presentation-planner/references/design-spec-schema.md +72 -0
- package/.github/skills/presentation-planner/references/handoff-contract.md +49 -0
- package/.github/skills/presentation-planner/references/responsibility-boundary.md +32 -0
- package/.github/skills/presentation-planner/references/scenario-templates.md +55 -0
- package/.github/skills/tech-writer/SKILL.md +434 -0
- package/.github/skills/tech-writer/assets/templates/blueprint.md +187 -0
- package/.github/skills/tech-writer/assets/templates/design-doc.md +29 -0
- package/.github/skills/tech-writer/assets/templates/migration-plan.md +173 -0
- package/.github/skills/tech-writer/assets/templates/operations-runbook.md +202 -0
- package/.github/skills/tech-writer/assets/templates/pr-description.md +23 -0
- package/.github/skills/tech-writer/assets/templates/qiita.md +44 -0
- package/.github/skills/tech-writer/assets/templates/readme.md +38 -0
- package/.github/skills/tech-writer/assets/templates/requirements-definition.md +170 -0
- package/.github/skills/tech-writer/assets/templates/rfi.md +113 -0
- package/.github/skills/tech-writer/assets/templates/rfp.md +180 -0
- package/.github/skills/tech-writer/assets/templates/security-design.md +167 -0
- package/.github/skills/tech-writer/assets/templates/system-design.md +220 -0
- package/.github/skills/tech-writer/assets/templates/technical-proposal.md +112 -0
- package/.github/skills/tech-writer/assets/templates/test-plan.md +153 -0
- package/.github/skills/tech-writer/assets/templates/user-manual.md +22 -0
- package/.github/skills/tech-writer/assets/templates/white-paper.md +192 -0
- package/.github/skills/tech-writer/references/doctypes/api-docs.md +33 -0
- package/.github/skills/tech-writer/references/doctypes/blueprint.md +81 -0
- package/.github/skills/tech-writer/references/doctypes/code-comments.md +39 -0
- package/.github/skills/tech-writer/references/doctypes/design-doc.md +42 -0
- package/.github/skills/tech-writer/references/doctypes/migration-plan.md +63 -0
- package/.github/skills/tech-writer/references/doctypes/operations-runbook.md +63 -0
- package/.github/skills/tech-writer/references/doctypes/pr-commit.md +82 -0
- package/.github/skills/tech-writer/references/doctypes/qiita.md +75 -0
- package/.github/skills/tech-writer/references/doctypes/readme.md +43 -0
- package/.github/skills/tech-writer/references/doctypes/release-notes.md +30 -0
- package/.github/skills/tech-writer/references/doctypes/requirements-definition.md +61 -0
- package/.github/skills/tech-writer/references/doctypes/rfi.md +43 -0
- package/.github/skills/tech-writer/references/doctypes/rfp.md +46 -0
- package/.github/skills/tech-writer/references/doctypes/security-design.md +71 -0
- package/.github/skills/tech-writer/references/doctypes/system-design.md +74 -0
- package/.github/skills/tech-writer/references/doctypes/technical-proposal.md +49 -0
- package/.github/skills/tech-writer/references/doctypes/test-plan.md +67 -0
- package/.github/skills/tech-writer/references/doctypes/user-manual.md +58 -0
- package/.github/skills/tech-writer/references/doctypes/white-paper.md +84 -0
- package/.github/skills/tech-writer/references/doctypes/zenn.md +66 -0
- package/.github/skills/tech-writer/references/japanese-prose-optimization.md +110 -0
- package/.github/skills/tech-writer/references/style-constitution.md +104 -0
- package/.github/skills/tech-writer/scripts/lint.py +412 -0
- package/LICENSE +21 -0
- package/README.md +92 -0
- package/bin/ai-data-scientist.js +123 -0
- package/package.json +41 -0
- package/pyproject.toml +45 -0
- package/src/ai_chemistry_scientist/__init__.py +0 -0
- package/src/ai_chemistry_scientist/admet_prediction.py +71 -0
- package/src/ai_chemistry_scientist/bioactivity_classification.py +73 -0
- package/src/ai_chemistry_scientist/data/sample_molecules.csv +21 -0
- package/src/ai_chemistry_scientist/dispatch.py +369 -0
- package/src/ai_chemistry_scientist/docking_score.py +97 -0
- package/src/ai_chemistry_scientist/drug_likeness_rules.py +84 -0
- package/src/ai_chemistry_scientist/evidence.py +41 -0
- package/src/ai_chemistry_scientist/molecular_descriptors.py +97 -0
- package/src/ai_chemistry_scientist/molecular_formula_mass.py +40 -0
- package/src/ai_chemistry_scientist/molecular_similarity.py +78 -0
- package/src/ai_chemistry_scientist/qsar_modeling.py +105 -0
- package/src/ai_chemistry_scientist/salt_standardization.py +81 -0
- package/src/ai_chemistry_scientist/structural_alerts.py +76 -0
- package/src/ai_chemistry_scientist/structure_format_conversion.py +84 -0
- package/src/ai_chemistry_scientist/validation.py +70 -0
- package/src/ai_data_scientist/__init__.py +0 -0
- package/src/ai_data_scientist/analysis_assumptions.py +121 -0
- package/src/ai_data_scientist/anomaly_detection.py +39 -0
- package/src/ai_data_scientist/automl.py +109 -0
- package/src/ai_data_scientist/cleaning.py +56 -0
- package/src/ai_data_scientist/cli.py +90 -0
- package/src/ai_data_scientist/clustering.py +54 -0
- package/src/ai_data_scientist/dashboard.py +33 -0
- package/src/ai_data_scientist/data_definition.py +100 -0
- package/src/ai_data_scientist/data_quality.py +164 -0
- package/src/ai_data_scientist/dataset_validation.py +135 -0
- package/src/ai_data_scientist/dependency_pins.py +60 -0
- package/src/ai_data_scientist/eda.py +82 -0
- package/src/ai_data_scientist/experiment_evaluation.py +635 -0
- package/src/ai_data_scientist/explainability.py +340 -0
- package/src/ai_data_scientist/feature_engineering.py +163 -0
- package/src/ai_data_scientist/gate_config.py +32 -0
- package/src/ai_data_scientist/ingestion.py +127 -0
- package/src/ai_data_scientist/insight_engine.py +180 -0
- package/src/ai_data_scientist/japanese_nlp.py +43 -0
- package/src/ai_data_scientist/jupyter_launcher.py +137 -0
- package/src/ai_data_scientist/jupyter_mcp_client.py +94 -0
- package/src/ai_data_scientist/language_router.py +28 -0
- package/src/ai_data_scientist/lifecycle.py +221 -0
- package/src/ai_data_scientist/mcp_gateway.py +113 -0
- package/src/ai_data_scientist/mcp_runtime.py +194 -0
- package/src/ai_data_scientist/mcp_transport.py +53 -0
- package/src/ai_data_scientist/ml_modeling.py +451 -0
- package/src/ai_data_scientist/model_tuning.py +104 -0
- package/src/ai_data_scientist/notebook_audit.py +574 -0
- package/src/ai_data_scientist/project_manager.py +243 -0
- package/src/ai_data_scientist/report_export.py +73 -0
- package/src/ai_data_scientist/sensitivity.py +445 -0
- package/src/ai_data_scientist/signal_analysis.py +201 -0
- package/src/ai_data_scientist/skill_packaging.py +40 -0
- package/src/ai_data_scientist/stats_analysis.py +88 -0
- package/src/ai_data_scientist/text_nlp.py +44 -0
- package/src/ai_data_scientist/timeseries.py +68 -0
- package/src/ai_data_scientist/visualization.py +708 -0
- package/src/ai_genomics_scientist/__init__.py +1 -0
- package/src/ai_genomics_scientist/differential_expression.py +147 -0
- package/src/ai_genomics_scientist/dispatch.py +267 -0
- package/src/ai_genomics_scientist/evidence.py +45 -0
- package/src/ai_genomics_scientist/gene_set_enrichment.py +76 -0
- package/src/ai_genomics_scientist/sequence_alignment.py +97 -0
- package/src/ai_genomics_scientist/sequence_features.py +111 -0
- package/src/ai_genomics_scientist/splice_site_scoring.py +66 -0
- package/src/ai_genomics_scientist/validation.py +83 -0
- package/src/ai_genomics_scientist/variant_effect.py +147 -0
- package/src/ai_genomics_scientist/variant_pathogenicity.py +125 -0
- package/src/ai_materials_scientist/__init__.py +0 -0
- package/src/ai_materials_scientist/calphad.py +117 -0
- package/src/ai_materials_scientist/classical_monte_carlo.py +165 -0
- package/src/ai_materials_scientist/crystal_plasticity.py +184 -0
- package/src/ai_materials_scientist/dispatch.py +100 -0
- package/src/ai_materials_scientist/evidence.py +84 -0
- package/src/ai_materials_scientist/fem.py +279 -0
- package/src/ai_materials_scientist/kinetic_monte_carlo.py +145 -0
- package/src/ai_materials_scientist/molecular_dynamics.py +240 -0
- package/src/ai_materials_scientist/phase_field.py +167 -0
- package/src/ai_materials_scientist/validation.py +70 -0
- package/src/ai_scientist/__init__.py +1 -0
- package/src/ai_scientist/completion_gate.py +15 -0
- package/src/ai_scientist/data_analysis.py +46 -0
- package/src/ai_scientist/evidence_registry.py +99 -0
- package/src/ai_scientist/experimental_design.py +20 -0
- package/src/ai_scientist/language.py +14 -0
- package/src/ai_scientist/latex_renderer.py +41 -0
- package/src/ai_scientist/literature_review.py +37 -0
- package/src/ai_scientist/manifest.py +87 -0
- package/src/ai_scientist/manuscript.py +94 -0
- package/src/ai_scientist/mcp_config.py +76 -0
- package/src/ai_scientist/mcp_external.py +42 -0
- package/src/ai_scientist/mcp_failures.py +23 -0
- package/src/ai_scientist/mcp_gateway.py +38 -0
- package/src/ai_scientist/mcp_managed.py +180 -0
- package/src/ai_scientist/npm_packaging.py +49 -0
- package/src/ai_scientist/orchestrator.py +133 -0
- package/src/ai_scientist/peer_review.py +60 -0
- package/src/ai_scientist/phase_gate.py +74 -0
- package/src/ai_scientist/phase_state.py +230 -0
- package/src/ai_scientist/presentation.py +56 -0
- package/src/ai_scientist/project_config.py +31 -0
- package/src/ai_scientist/project_handle.py +74 -0
- package/src/ai_scientist/reproducibility.py +20 -0
- package/src/ai_scientist/research_planning.py +20 -0
- package/src/ai_scientist/skill_invocation.py +21 -0
- package/src/ai_scientist/tdd_gate.py +99 -0
- package/src/ai_structural_biology_scientist/__init__.py +0 -0
- package/src/ai_structural_biology_scientist/contact_map.py +87 -0
- package/src/ai_structural_biology_scientist/dispatch.py +269 -0
- package/src/ai_structural_biology_scientist/evidence.py +43 -0
- package/src/ai_structural_biology_scientist/hydrophobicity.py +101 -0
- package/src/ai_structural_biology_scientist/protein_docking_score.py +104 -0
- package/src/ai_structural_biology_scientist/secondary_structure.py +95 -0
- package/src/ai_structural_biology_scientist/structural_similarity.py +74 -0
- package/src/ai_structural_biology_scientist/validation.py +100 -0
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
# Migration plan type
|
|
2
|
+
|
|
3
|
+
A migration plan defines how data, users, integrations, and business
|
|
4
|
+
processes move from a current state to a target state with measurable
|
|
5
|
+
validation, controlled downtime, and a tested rollback path.
|
|
6
|
+
|
|
7
|
+
## Target reader
|
|
8
|
+
|
|
9
|
+
Migration leads, application and data engineers, business owners, operators,
|
|
10
|
+
support teams, security reviewers, and Go/No-Go approvers.
|
|
11
|
+
|
|
12
|
+
## Settle before writing
|
|
13
|
+
|
|
14
|
+
- The current and target states and complete migration inventory
|
|
15
|
+
- Allowed downtime, data-loss tolerance, and business continuity needs
|
|
16
|
+
- Migration approach, waves, dependencies, and change-freeze conditions
|
|
17
|
+
- Reconciliation and business-acceptance criteria
|
|
18
|
+
- Go/No-Go and rollback authority, triggers, and deadlines
|
|
19
|
+
- Rehearsal evidence, communication needs, and post-migration support
|
|
20
|
+
|
|
21
|
+
## Responsibility boundary
|
|
22
|
+
|
|
23
|
+
Own the executable transition plan and its decisions. Link to implementation
|
|
24
|
+
scripts rather than embedding large programs. Do not claim rollback is
|
|
25
|
+
possible unless the plan states how post-cutover writes and data consistency
|
|
26
|
+
will be handled.
|
|
27
|
+
|
|
28
|
+
The migration section in `system-design` is sufficient for describing the
|
|
29
|
+
chosen transition architecture. Use a standalone `migration-plan` when the
|
|
30
|
+
cutover needs rehearsals, a timed procedure, business communications,
|
|
31
|
+
Go/No-Go gates, reconciliation evidence, or separate approval. When both
|
|
32
|
+
exist, the migration plan is authoritative for execution and the system
|
|
33
|
+
design summarizes the strategy and links to it.
|
|
34
|
+
|
|
35
|
+
## Template
|
|
36
|
+
|
|
37
|
+
Start from `assets/templates/migration-plan.md`.
|
|
38
|
+
The template is the Japanese-language skeleton; translate its headings when
|
|
39
|
+
the target document is English.
|
|
40
|
+
|
|
41
|
+
## Recommended skeleton
|
|
42
|
+
|
|
43
|
+
1. Agreement target, current and target states, scope, and constraints
|
|
44
|
+
2. Inventory, dependencies, mappings, transformation, and migration method
|
|
45
|
+
3. Roles, rehearsals, readiness, and timed production procedure
|
|
46
|
+
4. Reconciliation, Go/No-Go gates, rollback, and business continuity
|
|
47
|
+
5. Security, communication, stabilization, decommissioning, and approval
|
|
48
|
+
|
|
49
|
+
## Checklist
|
|
50
|
+
|
|
51
|
+
- [ ] Are all data, configuration, identities, integrations, and business
|
|
52
|
+
processes inventoried with owners and dependencies?
|
|
53
|
+
- [ ] Are mapping, transformation, default, rejection, retry, and idempotency
|
|
54
|
+
rules explicit?
|
|
55
|
+
- [ ] Have full-scale timing, validation, and rollback been rehearsed?
|
|
56
|
+
- [ ] Are start, cutover, reopen, Go/No-Go, and rollback conditions objective?
|
|
57
|
+
- [ ] Do reconciliation checks cover counts, aggregates, referential
|
|
58
|
+
integrity, and business scenarios?
|
|
59
|
+
- [ ] Does rollback address writes made after cutover and its last safe time?
|
|
60
|
+
- [ ] Are downtime communications, alternative operations, support, security,
|
|
61
|
+
temporary access, and evidence covered?
|
|
62
|
+
- [ ] Are stabilization, cleanup, old-system retention, and decommissioning
|
|
63
|
+
conditions defined?
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
# Operations design and runbook type
|
|
2
|
+
|
|
3
|
+
An operations design and runbook makes a production service observable,
|
|
4
|
+
changeable, recoverable, and supportable. It combines stable operating
|
|
5
|
+
policies with executable procedures for routine work and incidents.
|
|
6
|
+
|
|
7
|
+
## Target reader
|
|
8
|
+
|
|
9
|
+
Service owners, on-call engineers, operators, support staff, security teams,
|
|
10
|
+
change approvers, and incident commanders.
|
|
11
|
+
|
|
12
|
+
## Settle before writing
|
|
13
|
+
|
|
14
|
+
- The service boundary, owners, dependencies, and operating hours
|
|
15
|
+
- SLI, SLO, alert, capacity, backup, RTO, and RPO targets
|
|
16
|
+
- On-call, escalation, change, and incident authority
|
|
17
|
+
- Access requirements and safety constraints for operational actions
|
|
18
|
+
- The symptoms and failure scenarios that require executable runbooks
|
|
19
|
+
- Review, exercise, and expiration frequency
|
|
20
|
+
|
|
21
|
+
## Responsibility boundary
|
|
22
|
+
|
|
23
|
+
Write steps that an authorized operator can execute and verify. Link to
|
|
24
|
+
automation where it exists, but preserve preconditions, safety checks,
|
|
25
|
+
expected results, escalation, and recovery behavior. Never include secret
|
|
26
|
+
values or bypass access and change controls.
|
|
27
|
+
|
|
28
|
+
The operations section in `system-design` is sufficient for architectural
|
|
29
|
+
operability decisions. Use a standalone `operations-runbook` when on-call
|
|
30
|
+
staff need executable procedures, alerts, escalation, exercises, or a review
|
|
31
|
+
cycle independent of the system design. When both exist, the runbook is
|
|
32
|
+
authoritative for live operations and the system design links to its current
|
|
33
|
+
approved version.
|
|
34
|
+
|
|
35
|
+
## Template
|
|
36
|
+
|
|
37
|
+
Start from `assets/templates/operations-runbook.md`.
|
|
38
|
+
The template is the Japanese-language skeleton; translate its headings when
|
|
39
|
+
the target document is English.
|
|
40
|
+
|
|
41
|
+
## Recommended skeleton
|
|
42
|
+
|
|
43
|
+
1. Service scope, dependencies, levels, owners, and escalation
|
|
44
|
+
2. Observability, alerts, routine work, and capacity management
|
|
45
|
+
3. Incident severity, common initial response, and symptom runbooks
|
|
46
|
+
4. Start, stop, restore, security, change, and rollback procedures
|
|
47
|
+
5. Disaster recovery, business continuity, risks, exercises, and review
|
|
48
|
+
|
|
49
|
+
## Checklist
|
|
50
|
+
|
|
51
|
+
- [ ] Can an unfamiliar authorized operator identify the service, owner,
|
|
52
|
+
dependencies, dashboards, communication channels, and impact?
|
|
53
|
+
- [ ] Are SLI/SLO calculations, alert conditions, suppression, and test
|
|
54
|
+
frequency specified?
|
|
55
|
+
- [ ] Does every procedure state preconditions, safety limits, steps,
|
|
56
|
+
expected results, evidence, escalation, and recovery?
|
|
57
|
+
- [ ] Are backup restoration, RTO/RPO, disaster recovery, and exercises
|
|
58
|
+
executable and owned?
|
|
59
|
+
- [ ] Are access, secret, certificate, vulnerability, audit, and security
|
|
60
|
+
incident operations covered without exposing secret values?
|
|
61
|
+
- [ ] Are releases, emergency changes, rollback, and post-change checks clear?
|
|
62
|
+
- [ ] Are capacity, cost, routine maintenance, review dates, and stale
|
|
63
|
+
runbook detection addressed?
|
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
# PR description / commit message / issue report type
|
|
2
|
+
|
|
3
|
+
This doctype directly affects a reviewer's decision speed, so apply it more
|
|
4
|
+
strictly than the other types.
|
|
5
|
+
|
|
6
|
+
## Commit messages
|
|
7
|
+
|
|
8
|
+
### Format
|
|
9
|
+
|
|
10
|
+
```text
|
|
11
|
+
<type>: <summary (imperative mood, ~50 chars)>
|
|
12
|
+
|
|
13
|
+
<body (optional) - what and why the change was made; the diff already
|
|
14
|
+
shows the "what" implementation details, so don't repeat them>
|
|
15
|
+
|
|
16
|
+
<footer (optional) - Fixes #123, BREAKING CHANGE: ... etc.>
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
- Use imperative mood consistently in the summary line (e.g. "Fix", not
|
|
20
|
+
"Fixed"/"Fixes").
|
|
21
|
+
- The body should explain *why* the change was made, not restate *what*
|
|
22
|
+
changed — the diff already shows that.
|
|
23
|
+
- One concern per commit. Don't bundle unrelated changes into one commit
|
|
24
|
+
message.
|
|
25
|
+
|
|
26
|
+
### Checklist
|
|
27
|
+
|
|
28
|
+
- [ ] Can the change be inferred from the summary line alone (not just
|
|
29
|
+
"fix" or "update")?
|
|
30
|
+
- [ ] Does the body explain "why" rather than paraphrase the diff?
|
|
31
|
+
- [ ] Is the related issue number in the footer?
|
|
32
|
+
|
|
33
|
+
## PR descriptions
|
|
34
|
+
|
|
35
|
+
### Recommended skeleton
|
|
36
|
+
|
|
37
|
+
1. **What**: what changed, in 1–3 sentences.
|
|
38
|
+
2. **Why**: why this change is needed (link to the background issue, bug
|
|
39
|
+
report, or request).
|
|
40
|
+
3. **How**: the main approach. Leave implementation detail to code
|
|
41
|
+
comments and the diff; state only the design decisions here.
|
|
42
|
+
4. **How to verify**: concrete steps the reviewer can use to reproduce and
|
|
43
|
+
verify — test commands, or where to find screenshots/GIFs.
|
|
44
|
+
5. **Impact / breaking changes**: state explicitly if this affects other
|
|
45
|
+
teams' code or API consumers.
|
|
46
|
+
6. **Remaining work / follow-ups** (if applicable): preempt likely review
|
|
47
|
+
questions about unfinished items.
|
|
48
|
+
|
|
49
|
+
### Checklist
|
|
50
|
+
|
|
51
|
+
- [ ] Are What/Why/How separated, so reading only "What" gives the shape
|
|
52
|
+
of the change?
|
|
53
|
+
- [ ] Are there concrete steps (commands, URLs, repro conditions) the
|
|
54
|
+
reviewer can use to verify locally?
|
|
55
|
+
- [ ] Are breaking changes, DB migrations, config changes — anything a
|
|
56
|
+
reviewer could miss and cause an incident — near the top?
|
|
57
|
+
- [ ] Is there a link to the related issue/ticket?
|
|
58
|
+
- [ ] For UI changes, are screenshots actually attached?
|
|
59
|
+
|
|
60
|
+
## Issue reports (bug reports / feature requests)
|
|
61
|
+
|
|
62
|
+
### Bug report skeleton
|
|
63
|
+
|
|
64
|
+
1. **Summary**: the symptom, in one sentence.
|
|
65
|
+
2. **Steps to reproduce**: numbered, with environment info (version, OS,
|
|
66
|
+
browser, etc.) stated *before* the steps.
|
|
67
|
+
3. **Expected vs. actual result**: contrast them explicitly.
|
|
68
|
+
4. **Impact**: who is affected, and how often.
|
|
69
|
+
|
|
70
|
+
### Feature request skeleton
|
|
71
|
+
|
|
72
|
+
1. **Problem to solve**: state the situation causing pain before the
|
|
73
|
+
feature itself.
|
|
74
|
+
2. **Proposed solution** (optional): if you have one in mind.
|
|
75
|
+
3. **Alternatives considered** (optional).
|
|
76
|
+
|
|
77
|
+
### Checklist (issues, common)
|
|
78
|
+
|
|
79
|
+
- [ ] Are the repro steps (or use case) concrete enough to reproduce
|
|
80
|
+
independent of the reader's environment?
|
|
81
|
+
- [ ] Are "expected" and "actual" explicitly contrasted (bug reports)?
|
|
82
|
+
- [ ] Is environment info stated before the repro steps?
|
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
# Qiita article type
|
|
2
|
+
|
|
3
|
+
The article title lives in YAML frontmatter. Qiita's readership skews toward
|
|
4
|
+
searching for a specific error message or task, so apply rule 3 (order
|
|
5
|
+
matching how the reader looks for information) especially strictly here.
|
|
6
|
+
|
|
7
|
+
## Target reader
|
|
8
|
+
|
|
9
|
+
A developer who arrived via search for a specific error, API, or task, and
|
|
10
|
+
is scanning to confirm this article addresses their exact situation.
|
|
11
|
+
|
|
12
|
+
## Format
|
|
13
|
+
|
|
14
|
+
Markdown, with Qiita's frontmatter and a few platform-specific extensions
|
|
15
|
+
on top of GFM. The frontmatter `title` is the article title; body sections
|
|
16
|
+
start at `#`, with `##` used for subsections.
|
|
17
|
+
|
|
18
|
+
## Recommended frontmatter
|
|
19
|
+
|
|
20
|
+
```yaml
|
|
21
|
+
---
|
|
22
|
+
title: <Article title>
|
|
23
|
+
tags:
|
|
24
|
+
- <tag1>
|
|
25
|
+
- <tag2>
|
|
26
|
+
private: false # true: limited-share draft, false: public
|
|
27
|
+
organization_url_name: null # only if publishing under an Organization
|
|
28
|
+
---
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
- `title` and `tags` are required; `private` defaults the article to
|
|
32
|
+
public once posted, so confirm it deliberately rather than leaving the
|
|
33
|
+
default unconsidered.
|
|
34
|
+
- Qiita CLI also manages `updated_at`/`id`/`slide`/`ignorePublish` fields
|
|
35
|
+
automatically on publish/update — don't hand-edit those unless you know
|
|
36
|
+
why.
|
|
37
|
+
|
|
38
|
+
## Template
|
|
39
|
+
|
|
40
|
+
Start from `assets/templates/qiita.md`.
|
|
41
|
+
Use `#` for the highest-level body sections and `##` for their subsections.
|
|
42
|
+
|
|
43
|
+
## Recommended skeleton
|
|
44
|
+
|
|
45
|
+
1. **Lead paragraph (right after frontmatter, before any heading)**: the
|
|
46
|
+
specific problem/error/task this article addresses and what the reader
|
|
47
|
+
will be able to do — this is rule 1's "first three lines" analog, since
|
|
48
|
+
there's no in-body title to carry it.
|
|
49
|
+
2. **Environment / versions**: state the exact versions (language,
|
|
50
|
+
framework, OS) the article was verified against, before any steps —
|
|
51
|
+
Qiita readers frequently hit version-specific breakage.
|
|
52
|
+
3. **Body sections, one concern per `#` heading**: order by how a reader
|
|
53
|
+
arriving via search would scan (rule 3) — put the fix/answer before
|
|
54
|
+
background explanation if the article is troubleshooting-oriented. Use
|
|
55
|
+
`##` only for subsections within one concern.
|
|
56
|
+
4. **Code blocks with both a language tag and, where relevant, a filename**:
|
|
57
|
+
Qiita supports ` ```js:example.js ` — prefer this over a bare language
|
|
58
|
+
tag when the file identity matters to the reader.
|
|
59
|
+
5. **References / further reading** (if applicable): official docs or
|
|
60
|
+
related articles, not a restatement of the body.
|
|
61
|
+
|
|
62
|
+
## Checklist
|
|
63
|
+
|
|
64
|
+
- [ ] Are `title` and `tags` present, and is `private` a deliberate choice
|
|
65
|
+
rather than an unconsidered default?
|
|
66
|
+
- [ ] Does the lead paragraph right after frontmatter state the specific
|
|
67
|
+
problem/task addressed, since there's no in-body title to do that?
|
|
68
|
+
- [ ] Do highest-level body sections use `#`, with `##` reserved for
|
|
69
|
+
subsections?
|
|
70
|
+
- [ ] Are the exact versions/environment stated before the steps?
|
|
71
|
+
- [ ] For troubleshooting-oriented articles, does the fix appear before
|
|
72
|
+
background explanation, matching how a reader arriving via search
|
|
73
|
+
would scan?
|
|
74
|
+
- [ ] Do code blocks carry a language tag (and a filename where the file
|
|
75
|
+
identity matters)?
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
# README type
|
|
2
|
+
|
|
3
|
+
The recommended skeleton and checklist for a project README: the document
|
|
4
|
+
most readers see first, and the one that decides whether they keep reading.
|
|
5
|
+
|
|
6
|
+
## Target reader
|
|
7
|
+
|
|
8
|
+
Someone visiting this repository for the first time. They want to judge
|
|
9
|
+
"what is this", "do I need it", and "how do I start" within seconds.
|
|
10
|
+
|
|
11
|
+
## Recommended skeleton
|
|
12
|
+
|
|
13
|
+
1. **Title + one-sentence description**: right after the project name, say
|
|
14
|
+
what it does in one sentence.
|
|
15
|
+
2. **What problem it solves (Why)**: problem → approach in 2–4 sentences,
|
|
16
|
+
before the feature list.
|
|
17
|
+
3. **Key features / what you can do**: a bullet list, one feature per item,
|
|
18
|
+
starting with a verb.
|
|
19
|
+
4. **Install / setup**: a command sequence that runs as copy-pasted.
|
|
20
|
+
Prerequisites (versions, OS, permissions) go in a separate section
|
|
21
|
+
*before* the steps.
|
|
22
|
+
5. **Quickstart, headed with what it does**: the smallest successful
|
|
23
|
+
experience (a "hello world" equivalent) first, under a heading that
|
|
24
|
+
previews the concrete task (e.g. "Send your first request"), not the
|
|
25
|
+
generic label "Usage" (structure constitution rule 2). Move advanced
|
|
26
|
+
usage to a separate, similarly specific heading.
|
|
27
|
+
6. **Configuration / options** (if applicable): a table (key, default,
|
|
28
|
+
description).
|
|
29
|
+
7. **Known limitations / what's not supported**: don't omit this.
|
|
30
|
+
8. **Contributing / license**: fine to leave at the end.
|
|
31
|
+
|
|
32
|
+
## Checklist
|
|
33
|
+
|
|
34
|
+
- [ ] Does the one-sentence description right after the title convey "what
|
|
35
|
+
this does"?
|
|
36
|
+
- [ ] Do the install steps run top-to-bottom via copy-paste (no
|
|
37
|
+
prerequisite hidden mid-steps)?
|
|
38
|
+
- [ ] Is the quickstart section headed with a specific, task-previewing
|
|
39
|
+
label instead of the generic "Usage", and does it show the smallest
|
|
40
|
+
successful experience rather than an exhaustive feature list?
|
|
41
|
+
- [ ] Do badges/acknowledgments/license come after the main content, not
|
|
42
|
+
before it?
|
|
43
|
+
- [ ] Does a known-limitations section exist?
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
# Release notes / CHANGELOG type
|
|
2
|
+
|
|
3
|
+
The recommended skeleton and checklist for a per-version changelog entry,
|
|
4
|
+
written for a reader deciding whether and how to upgrade.
|
|
5
|
+
|
|
6
|
+
## Target reader
|
|
7
|
+
|
|
8
|
+
An existing user deciding whether to upgrade. Reading time: seconds to a
|
|
9
|
+
few tens of seconds.
|
|
10
|
+
|
|
11
|
+
## Recommended skeleton
|
|
12
|
+
|
|
13
|
+
1. **Version + date**: always include both in the heading.
|
|
14
|
+
2. **Breaking changes (topmost, if any)**: what breaks, with a link to the
|
|
15
|
+
migration steps. This is the one section that must never be omitted or
|
|
16
|
+
deferred.
|
|
17
|
+
3. **Added / Changed / Fixed / Deprecated / Removed**: categorize per
|
|
18
|
+
[Keep a Changelog](https://keepachangelog.com/). One change per item,
|
|
19
|
+
starting with a verb.
|
|
20
|
+
4. **Notes on affected user segments** (if applicable): scope it, e.g.
|
|
21
|
+
"affects only users of X".
|
|
22
|
+
|
|
23
|
+
## Checklist
|
|
24
|
+
|
|
25
|
+
- [ ] Are breaking changes at the top, with a migration path (or link)?
|
|
26
|
+
- [ ] Does each item state "what changed and how" in one sentence (not a
|
|
27
|
+
raw copy of the commit message)?
|
|
28
|
+
- [ ] Do the categories (Added/Changed/Fixed, etc.) match the actual
|
|
29
|
+
change?
|
|
30
|
+
- [ ] Are both the version number and the date stated?
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
# Requirements definition type
|
|
2
|
+
|
|
3
|
+
A requirements definition establishes agreement on what outcomes, scope,
|
|
4
|
+
capabilities, quality levels, and acceptance conditions a system must
|
|
5
|
+
satisfy. It describes the required behavior and measurable constraints
|
|
6
|
+
without prematurely prescribing the implementation architecture.
|
|
7
|
+
|
|
8
|
+
## Target reader
|
|
9
|
+
|
|
10
|
+
Business owners, product owners, users, architects, delivery teams,
|
|
11
|
+
operators, security reviewers, and approvers who must agree on what will be
|
|
12
|
+
built and how acceptance will be judged.
|
|
13
|
+
|
|
14
|
+
## Settle before writing
|
|
15
|
+
|
|
16
|
+
- The business problem, target users, and measurable outcome
|
|
17
|
+
- In-scope and out-of-scope business processes, systems, and data
|
|
18
|
+
- Requirement priorities and the authority that resolves conflicts
|
|
19
|
+
- Constraints covering budget, schedule, law, policy, and existing systems
|
|
20
|
+
- Measurable acceptance conditions for functional and non-functional needs
|
|
21
|
+
- The identifier or naming convention used for traceability
|
|
22
|
+
|
|
23
|
+
## Responsibility boundary
|
|
24
|
+
|
|
25
|
+
State what the system must achieve and the constraints it must meet. Do not
|
|
26
|
+
turn preferred products, component layouts, database schemas, or deployment
|
|
27
|
+
topologies into requirements unless they are genuine externally imposed
|
|
28
|
+
constraints. Put implementation choices in a system design document and
|
|
29
|
+
link them back to requirement IDs.
|
|
30
|
+
|
|
31
|
+
## Template
|
|
32
|
+
|
|
33
|
+
Start from `assets/templates/requirements-definition.md`.
|
|
34
|
+
The template is the Japanese-language skeleton; translate its headings when
|
|
35
|
+
the target document is English.
|
|
36
|
+
|
|
37
|
+
## Recommended skeleton
|
|
38
|
+
|
|
39
|
+
1. Agreement target, background, problem, purpose, and success measures
|
|
40
|
+
2. Scope, stakeholders, assumptions, and constraints
|
|
41
|
+
3. Business flow, business rules, and prioritized functional requirements
|
|
42
|
+
4. Measurable non-functional, data, and external-interface requirements
|
|
43
|
+
5. Migration, operation, acceptance, and traceability
|
|
44
|
+
6. Risks, open questions, approval, and change history
|
|
45
|
+
|
|
46
|
+
## Checklist
|
|
47
|
+
|
|
48
|
+
- [ ] Are purpose, scope, exclusions, stakeholders, assumptions, and
|
|
49
|
+
constraints explicit?
|
|
50
|
+
- [ ] Does every requirement have a stable ID, priority, and independently
|
|
51
|
+
verifiable acceptance condition?
|
|
52
|
+
- [ ] Are non-functional requirements measurable under stated conditions?
|
|
53
|
+
- [ ] Are data ownership, classification, retention, quality, and deletion
|
|
54
|
+
requirements covered?
|
|
55
|
+
- [ ] Are external interfaces, migration, operations, and failure handling
|
|
56
|
+
included where applicable?
|
|
57
|
+
- [ ] Can each requirement be traced to a problem or objective and forward
|
|
58
|
+
to an acceptance test and design or implementation artifact?
|
|
59
|
+
- [ ] Are implementation preferences separated from actual constraints?
|
|
60
|
+
- [ ] Are unresolved items owned and time-bound, with approval and change
|
|
61
|
+
history recorded?
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
# Request for information (RFI) type
|
|
2
|
+
|
|
3
|
+
An RFI gathers market, vendor, product, feasibility, and indicative pricing
|
|
4
|
+
information before requirements or procurement strategy are final. It must
|
|
5
|
+
not read like an award decision or demand proposal-level effort.
|
|
6
|
+
|
|
7
|
+
## Target reader
|
|
8
|
+
|
|
9
|
+
Potential suppliers preparing an overview-level response, and the internal
|
|
10
|
+
team using those responses to refine requirements and decide whether to
|
|
11
|
+
proceed to an RFP.
|
|
12
|
+
|
|
13
|
+
## Settle before writing
|
|
14
|
+
|
|
15
|
+
- The unknowns the market research must resolve
|
|
16
|
+
- The respondent population and distribution/confidentiality level
|
|
17
|
+
- The current-environment details safe to disclose before an NDA
|
|
18
|
+
- The response schedule and single source of truth for dates
|
|
19
|
+
- The intended next step, while avoiding any promise to issue an RFP
|
|
20
|
+
|
|
21
|
+
## Template
|
|
22
|
+
|
|
23
|
+
Start from `assets/templates/rfi.md`.
|
|
24
|
+
The template is the Japanese-language skeleton; translate its headings when
|
|
25
|
+
the target document is English.
|
|
26
|
+
|
|
27
|
+
## Recommended skeleton
|
|
28
|
+
|
|
29
|
+
1. Purpose, non-procurement disclaimer, and current context
|
|
30
|
+
2. Overview-level company, product, architecture, and security questions
|
|
31
|
+
3. Indicative implementation, support, roadmap, and pricing information
|
|
32
|
+
4. Response format, authoritative schedule, and handling conditions
|
|
33
|
+
5. Respondent checklist
|
|
34
|
+
|
|
35
|
+
## Checklist
|
|
36
|
+
|
|
37
|
+
- [ ] Does the document state that responses are not scored or ranked?
|
|
38
|
+
- [ ] Does it request overview-level information rather than detailed design?
|
|
39
|
+
- [ ] Are indicative prices clearly non-binding?
|
|
40
|
+
- [ ] Are roadmap, constraints, and unsupported capabilities reportable?
|
|
41
|
+
- [ ] Is sensitive configuration moved to an NDA-controlled annex?
|
|
42
|
+
- [ ] Is the schedule the single source of truth for dates?
|
|
43
|
+
- [ ] Does the disclaimer avoid promising procurement or an RFP?
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
# Request for proposal (RFP) type
|
|
2
|
+
|
|
3
|
+
An RFP asks qualified suppliers for comparable, evaluable, and
|
|
4
|
+
contract-ready proposals against explicit requirements, acceptance criteria,
|
|
5
|
+
commercial terms, and a disclosed evaluation method.
|
|
6
|
+
|
|
7
|
+
## Target reader
|
|
8
|
+
|
|
9
|
+
Suppliers deciding whether and how to bid, evaluators scoring proposals, and
|
|
10
|
+
procurement or legal reviewers preparing the resulting contract.
|
|
11
|
+
|
|
12
|
+
## Settle before writing
|
|
13
|
+
|
|
14
|
+
- Procurement scope, exclusions, budget model, and contract term
|
|
15
|
+
- Must/Should/Could requirements and the consequence of failing a Must
|
|
16
|
+
- Measurable acceptance criteria and payment milestones
|
|
17
|
+
- Bidder eligibility, security, compliance, and subcontracting conditions
|
|
18
|
+
- TCO period, price-scoring formula, category weights, and pass thresholds
|
|
19
|
+
- The authoritative procurement schedule and confidentiality controls
|
|
20
|
+
|
|
21
|
+
## Template
|
|
22
|
+
|
|
23
|
+
Start from `assets/templates/rfp.md`.
|
|
24
|
+
The template is the Japanese-language skeleton; translate its headings when
|
|
25
|
+
the target document is English.
|
|
26
|
+
|
|
27
|
+
## Recommended skeleton
|
|
28
|
+
|
|
29
|
+
1. Procurement purpose, scope, exclusions, and current environment
|
|
30
|
+
2. Functional, non-functional, security, migration, and support requirements
|
|
31
|
+
3. Bidder eligibility, deliverables, acceptance, and payment
|
|
32
|
+
4. Requested proposal contents, implementation schedule, and TCO pricing
|
|
33
|
+
5. Evaluation formula, submission process, authoritative schedule, and terms
|
|
34
|
+
6. Bidder submission checklist
|
|
35
|
+
|
|
36
|
+
## Checklist
|
|
37
|
+
|
|
38
|
+
- [ ] Can every functional and non-functional requirement be answered in a
|
|
39
|
+
structured, comparable format?
|
|
40
|
+
- [ ] Are Must failures and bidder disqualification rules explicit?
|
|
41
|
+
- [ ] Are deliverables linked to acceptance and payment conditions?
|
|
42
|
+
- [ ] Are bidder eligibility and conflict/subcontractor disclosures covered?
|
|
43
|
+
- [ ] Can all price rows be normalized into the stated TCO period?
|
|
44
|
+
- [ ] Is the scoring formula reproducible by independent evaluators?
|
|
45
|
+
- [ ] Is sensitive environment detail isolated in an NDA-controlled annex?
|
|
46
|
+
- [ ] Is the schedule the single source of truth for all procurement dates?
|
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
# Security design and threat model type
|
|
2
|
+
|
|
3
|
+
A security design and threat model identifies protected assets, trust
|
|
4
|
+
boundaries, threats, controls, verification, and residual risk. It turns
|
|
5
|
+
security and compliance requirements into reviewable implementation and
|
|
6
|
+
operational decisions.
|
|
7
|
+
|
|
8
|
+
## Target reader
|
|
9
|
+
|
|
10
|
+
Architects, developers, platform and security engineers, privacy and
|
|
11
|
+
compliance reviewers, operators, and accountable risk acceptors.
|
|
12
|
+
|
|
13
|
+
## Settle before writing
|
|
14
|
+
|
|
15
|
+
- System scope, architecture, data flows, trust boundaries, and environments
|
|
16
|
+
- Assets, owners, sensitivity, retention, and regulatory obligations
|
|
17
|
+
- Identities, roles, administrative paths, and external dependencies
|
|
18
|
+
- Threat-model method and risk-rating approach
|
|
19
|
+
- Security testing, exception, and residual-risk acceptance authority
|
|
20
|
+
- The approved requirements and system-design baselines
|
|
21
|
+
|
|
22
|
+
## Responsibility boundary
|
|
23
|
+
|
|
24
|
+
Document security decisions and trace threats to controls and tests. Do not
|
|
25
|
+
include credentials, private keys, exploitable production details, or
|
|
26
|
+
instructions that bypass controls. Vulnerability findings needing restricted
|
|
27
|
+
handling belong in the repository's approved security-reporting channel.
|
|
28
|
+
|
|
29
|
+
The security section in `system-design` is sufficient for an integrated
|
|
30
|
+
architecture summary. Use a standalone `security-design` when threat
|
|
31
|
+
modeling, control ownership, compliance evidence, exceptions, or risk
|
|
32
|
+
acceptance needs independent review. When both exist, the security design is
|
|
33
|
+
authoritative for threats, controls, and residual risk.
|
|
34
|
+
|
|
35
|
+
This document owns security-test intent by tracing requirements and threats
|
|
36
|
+
to controls and planned tests, including the expected environment class and
|
|
37
|
+
required evidence type. The `test-plan` owns actual execution environments,
|
|
38
|
+
schedule, release gates, results, and evidence storage; copy the security
|
|
39
|
+
test IDs, threat IDs, and control IDs into its traceability table.
|
|
40
|
+
|
|
41
|
+
## Template
|
|
42
|
+
|
|
43
|
+
Start from `assets/templates/security-design.md`.
|
|
44
|
+
The template is the Japanese-language skeleton; translate its headings when
|
|
45
|
+
the target document is English.
|
|
46
|
+
|
|
47
|
+
## Recommended skeleton
|
|
48
|
+
|
|
49
|
+
1. Scope, requirements, assets, data classification, and architecture
|
|
50
|
+
2. Trust boundaries, identity, authentication, authorization, and threats
|
|
51
|
+
3. Preventive, detective, and responsive controls with ownership
|
|
52
|
+
4. Data, secret, API, audit, vulnerability, and supply-chain protection
|
|
53
|
+
5. Security testing, incident response, residual risk, traceability, and approval
|
|
54
|
+
|
|
55
|
+
## Checklist
|
|
56
|
+
|
|
57
|
+
- [ ] Are system scope, assets, owners, data flows, and trust boundaries clear?
|
|
58
|
+
- [ ] Are identities, authentication, authorization, privilege, session, and
|
|
59
|
+
recovery paths covered?
|
|
60
|
+
- [ ] Does each credible threat identify affected assets, impact, likelihood,
|
|
61
|
+
controls, owner, and test?
|
|
62
|
+
- [ ] Are encryption, key and secret lifecycle, retention, deletion, masking,
|
|
63
|
+
logging, and audit addressed?
|
|
64
|
+
- [ ] Are input, output, API abuse, availability, dependency, build, artifact,
|
|
65
|
+
and supply-chain risks covered?
|
|
66
|
+
- [ ] Are security tests, incident response, evidence preservation, and
|
|
67
|
+
notification responsibilities defined?
|
|
68
|
+
- [ ] Is every exception time-bound, owned, compensated, and accepted by an
|
|
69
|
+
accountable risk owner?
|
|
70
|
+
- [ ] Can requirements, assets, threats, controls, tests, and implementation
|
|
71
|
+
locations be traced end to end?
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
# System design type
|
|
2
|
+
|
|
3
|
+
A system design explains how approved requirements will be realized through
|
|
4
|
+
architecture, components, data, interfaces, deployment, security, quality
|
|
5
|
+
controls, and operations. It must be detailed enough for implementation,
|
|
6
|
+
testing, operation, and review without duplicating source code.
|
|
7
|
+
|
|
8
|
+
## Target reader
|
|
9
|
+
|
|
10
|
+
Architects, developers, testers, operators, security reviewers, and technical
|
|
11
|
+
approvers who must verify that the design satisfies the requirements and can
|
|
12
|
+
be built and operated safely.
|
|
13
|
+
|
|
14
|
+
## Settle before writing
|
|
15
|
+
|
|
16
|
+
- The approved requirements baseline and stable requirement IDs
|
|
17
|
+
- The system boundary, design scope, environments, and external dependencies
|
|
18
|
+
- The most important quality attributes and their measurable targets
|
|
19
|
+
- Constraints on technology, deployment, security, compliance, cost, and time
|
|
20
|
+
- The level of design detail needed for implementation and review
|
|
21
|
+
- The owner of unresolved design decisions
|
|
22
|
+
|
|
23
|
+
## Responsibility boundary
|
|
24
|
+
|
|
25
|
+
Describe implementation choices and trace them to requirements. Do not
|
|
26
|
+
silently redefine scope or acceptance criteria from the requirements
|
|
27
|
+
definition. If the design exposes a missing, conflicting, or infeasible
|
|
28
|
+
requirement, record it as an open issue and update the approved requirements
|
|
29
|
+
through change control.
|
|
30
|
+
|
|
31
|
+
Use `design-doc` or an ADR for one isolated decision and its alternatives.
|
|
32
|
+
Use `system-design` when the reader needs the integrated design across
|
|
33
|
+
components, data, interfaces, deployment, quality attributes, and operations.
|
|
34
|
+
Its test, operation, migration, and security sections summarize the design
|
|
35
|
+
decisions needed to understand the whole system. Split out a `test-plan`,
|
|
36
|
+
`operations-runbook`, `migration-plan`, or `security-design` when that topic
|
|
37
|
+
needs executable procedures, independent evidence, a different approval
|
|
38
|
+
authority, or a separate lifecycle. When a standalone document exists, it is
|
|
39
|
+
the source of truth for that topic; the system design links to and summarizes
|
|
40
|
+
it instead of duplicating details.
|
|
41
|
+
|
|
42
|
+
## Template
|
|
43
|
+
|
|
44
|
+
Start from `assets/templates/system-design.md`.
|
|
45
|
+
The template is the Japanese-language skeleton; translate its headings when
|
|
46
|
+
the target document is English.
|
|
47
|
+
|
|
48
|
+
## Recommended skeleton
|
|
49
|
+
|
|
50
|
+
1. Agreement target, scope, assumptions, constraints, and design drivers
|
|
51
|
+
2. Context, container, component, and processing-flow design
|
|
52
|
+
3. Data, transaction, interface, and error-contract design
|
|
53
|
+
4. Security, performance, capacity, availability, and reliability design
|
|
54
|
+
5. Deployment, network, observability, operation, backup, and recovery
|
|
55
|
+
6. Migration, release, rollback, test traceability, trade-offs, and approval
|
|
56
|
+
|
|
57
|
+
## Checklist
|
|
58
|
+
|
|
59
|
+
- [ ] Is the design boundary clear, and is the approved requirements
|
|
60
|
+
baseline identified?
|
|
61
|
+
- [ ] Are major components assigned cohesive responsibilities with explicit
|
|
62
|
+
dependencies and interfaces?
|
|
63
|
+
- [ ] Are data ownership, schemas, integrity, transactions, retention, and
|
|
64
|
+
deletion addressed?
|
|
65
|
+
- [ ] Are authentication, authorization, encryption, audit, secrets, and
|
|
66
|
+
threat controls concrete and testable?
|
|
67
|
+
- [ ] Are performance, capacity, availability, timeout, retry, idempotency,
|
|
68
|
+
backup, RTO, and RPO decisions quantified?
|
|
69
|
+
- [ ] Are deployment, network boundaries, configuration, observability,
|
|
70
|
+
release, operation, and incident handling implementable?
|
|
71
|
+
- [ ] Are migration, compatibility, rollback, and failure recovery covered?
|
|
72
|
+
- [ ] Is every major design element traced to requirements and tests?
|
|
73
|
+
- [ ] Are rejected alternatives, accepted trade-offs, risks, open decisions,
|
|
74
|
+
reviewers, and change history recorded?
|