{
  "schemaVersion": "1.0",
  "item": {
    "slug": "architecture-decision-records",
    "name": "Architecture Decision Records",
    "source": "tencent",
    "type": "skill",
    "category": "内容创作",
    "sourceUrl": "https://clawhub.ai/wpank/architecture-decision-records",
    "canonicalUrl": "https://clawhub.ai/wpank/architecture-decision-records",
    "targetPlatform": "OpenClaw"
  },
  "install": {
    "downloadMode": "redirect",
    "downloadUrl": "/downloads/architecture-decision-records",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=architecture-decision-records",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "installMethod": "Manual import",
    "extraction": "Extract archive",
    "prerequisites": [
      "OpenClaw"
    ],
    "packageFormat": "ZIP package",
    "includedAssets": [
      "README.md",
      "SKILL.md"
    ],
    "primaryDoc": "SKILL.md",
    "quickSetup": [
      "Download the package from Yavira.",
      "Extract the archive and review SKILL.md first.",
      "Import or place the package into your OpenClaw setup."
    ],
    "agentAssist": {
      "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
      "steps": [
        "Download the package from Yavira.",
        "Extract it into a folder your agent can access.",
        "Paste one of the prompts below and point your agent at the extracted folder."
      ],
      "prompts": [
        {
          "label": "New install",
          "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Then review README.md for any prerequisites, environment setup, or post-install checks. Tell me what you changed and call out any manual steps you could not complete."
        },
        {
          "label": "Upgrade existing",
          "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Then review README.md for any prerequisites, environment setup, or post-install checks. Summarize what changed and any follow-up checks I should run."
        }
      ]
    },
    "sourceHealth": {
      "source": "tencent",
      "status": "healthy",
      "reason": "direct_download_ok",
      "recommendedAction": "download",
      "checkedAt": "2026-04-23T16:43:11.935Z",
      "expiresAt": "2026-04-30T16:43:11.935Z",
      "httpStatus": 200,
      "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=4claw-imageboard",
      "contentType": "application/zip",
      "probeMethod": "head",
      "details": {
        "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=4claw-imageboard",
        "contentDisposition": "attachment; filename=\"4claw-imageboard-1.0.1.zip\"",
        "redirectLocation": null,
        "bodySnippet": null
      },
      "scope": "source",
      "summary": "Source download looks usable.",
      "detail": "Yavira can redirect you to the upstream package for this source.",
      "primaryActionLabel": "Download for OpenClaw",
      "primaryActionHref": "/downloads/architecture-decision-records"
    },
    "validation": {
      "installChecklist": [
        "Use the Yavira download entry.",
        "Review SKILL.md after the package is downloaded.",
        "Confirm the extracted package contains the expected setup assets."
      ],
      "postInstallChecks": [
        "Confirm the extracted package includes the expected docs or setup files.",
        "Validate the skill or prompts are available in your target agent workspace.",
        "Capture any manual follow-up steps the agent could not complete."
      ]
    },
    "downloadPageUrl": "https://openagent3.xyz/downloads/architecture-decision-records",
    "agentPageUrl": "https://openagent3.xyz/skills/architecture-decision-records/agent",
    "manifestUrl": "https://openagent3.xyz/skills/architecture-decision-records/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/architecture-decision-records/agent.md"
  },
  "agentAssist": {
    "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
    "steps": [
      "Download the package from Yavira.",
      "Extract it into a folder your agent can access.",
      "Paste one of the prompts below and point your agent at the extracted folder."
    ],
    "prompts": [
      {
        "label": "New install",
        "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Then review README.md for any prerequisites, environment setup, or post-install checks. Tell me what you changed and call out any manual steps you could not complete."
      },
      {
        "label": "Upgrade existing",
        "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Then review README.md for any prerequisites, environment setup, or post-install checks. Summarize what changed and any follow-up checks I should run."
      }
    ]
  },
  "documentation": {
    "source": "clawhub",
    "primaryDoc": "SKILL.md",
    "sections": [
      {
        "title": "WHAT",
        "body": "Lightweight documentation capturing the context, decision, and consequences of significant technical choices. ADRs become the institutional memory of why things are built the way they are."
      },
      {
        "title": "WHEN",
        "body": "Adopting new frameworks or technologies\nChoosing between architectural approaches\nMaking database or infrastructure decisions\nDefining API design patterns\nAny decision that would be hard to reverse or understand later"
      },
      {
        "title": "KEYWORDS",
        "body": "ADR, architecture decision record, technical documentation, decision log, MADR, RFC, design decisions, trade-offs"
      },
      {
        "title": "Quick Decision: Should I Write an ADR?",
        "body": "Write ADRSkip ADRNew framework/language adoptionMinor version upgradesDatabase technology choiceBug fixesAPI design patternsImplementation detailsSecurity architectureRoutine maintenanceIntegration patternsConfiguration changesBreaking changesCode formatting"
      },
      {
        "title": "ADR Lifecycle",
        "body": "Proposed → Accepted → Deprecated → Superseded\n              ↓\n           Rejected\n\nNever modify accepted ADRs - write new ones to supersede."
      },
      {
        "title": "Template 1: Standard (Copy This)",
        "body": "# ADR-NNNN: [Title]\n\n## Status\n[Proposed | Accepted | Deprecated | Superseded by ADR-XXXX]\n\n## Context\n[What is the issue? What forces are at play? 2-3 paragraphs max.]\n\n## Decision\nWe will [decision statement].\n\n## Consequences\n\n### Positive\n- [Benefit 1]\n- [Benefit 2]\n\n### Negative\n- [Drawback 1]\n- [Drawback 2]\n\n### Risks\n- [Risk and mitigation]\n\n## Related\n- ADR-XXXX: [Related decision]"
      },
      {
        "title": "Template 2: Full (For Major Decisions)",
        "body": "# ADR-0001: Use PostgreSQL as Primary Database\n\n## Status\nAccepted\n\n## Context\nWe need to select a primary database for our e-commerce platform handling:\n- ~10,000 concurrent users\n- Complex product catalog with hierarchical categories\n- Transaction processing for orders and payments\n- Full-text search for products\n\nThe team has experience with MySQL, PostgreSQL, and MongoDB.\n\n## Decision Drivers\n- **Must have** ACID compliance for payment processing\n- **Must support** complex queries for reporting  \n- **Should support** full-text search to reduce infrastructure\n- **Should have** good JSON support for flexible product attributes\n\n## Considered Options\n\n### Option 1: PostgreSQL\n**Pros**: ACID compliant, excellent JSONB support, built-in full-text search, PostGIS\n**Cons**: Slightly more complex replication than MySQL\n\n### Option 2: MySQL\n**Pros**: Familiar to team, simple replication\n**Cons**: Weaker JSON support, no built-in full-text search\n\n### Option 3: MongoDB\n**Pros**: Flexible schema, native JSON\n**Cons**: No ACID for multi-document transactions, team has limited experience\n\n## Decision\nWe will use **PostgreSQL 15** as our primary database.\n\n## Rationale\nPostgreSQL provides the best balance of ACID compliance (essential for e-commerce), \nbuilt-in capabilities (reduces infrastructure), and team familiarity.\n\n## Consequences\n\n### Positive\n- Single database handles transactions, search, and geospatial\n- Reduced operational complexity\n- Strong consistency for financial data\n\n### Negative\n- Need PostgreSQL-specific training for team\n- Vertical scaling limits may require read replicas\n\n### Risks\n- Full-text search may not scale as well as Elasticsearch\n- **Mitigation**: Design for potential ES addition if needed\n\n## Implementation Notes\n- Use JSONB for flexible product attributes\n- Implement connection pooling with PgBouncer\n- Set up streaming replication for read replicas\n\n## Related\n- ADR-0002: Caching Strategy (Redis)\n- ADR-0005: Search Architecture"
      },
      {
        "title": "Template 3: Lightweight (For Smaller Decisions)",
        "body": "# ADR-0012: Adopt TypeScript for Frontend\n\n**Status**: Accepted  \n**Date**: 2024-01-15  \n**Deciders**: @alice, @bob\n\n## Context\nReact codebase has 50+ components with increasing bugs from prop type mismatches.\n\n## Decision\nAdopt TypeScript for all new frontend code. Migrate existing code incrementally.\n\n## Consequences\n**Good**: Catch type errors at compile time, better IDE support  \n**Bad**: Learning curve, initial slowdown  \n**Mitigation**: Training sessions, `allowJs: true` for gradual adoption"
      },
      {
        "title": "Template 4: Y-Statement (One-Liner)",
        "body": "# ADR-0015: API Gateway Selection\n\nIn the context of **building a microservices architecture**,\nfacing **the need for centralized API management and rate limiting**,\nwe decided for **Kong Gateway**\nand against **AWS API Gateway and custom Nginx**,\nto achieve **vendor independence and plugin extensibility**,\naccepting that **we need to manage Kong infrastructure ourselves**."
      },
      {
        "title": "Template 5: Deprecation ADR",
        "body": "# ADR-0020: Deprecate MongoDB in Favor of PostgreSQL\n\n## Status\nAccepted (Supersedes ADR-0003)\n\n## Context\nADR-0003 (2021) chose MongoDB for user profiles. Since then:\n- MongoDB transactions remain problematic for our use case\n- Our schema has stabilized and rarely changes\n- Maintaining two databases increases operational burden\n\n## Decision\nDeprecate MongoDB and migrate user profiles to PostgreSQL.\n\n## Migration Plan\n1. **Week 1-2**: Create PostgreSQL schema, enable dual-write\n2. **Week 3-4**: Backfill historical data, validate consistency\n3. **Week 5**: Switch reads to PostgreSQL\n4. **Week 6**: Remove MongoDB writes, decommission\n\n## Lessons Learned\n- Schema flexibility benefits were overestimated\n- Operational cost of multiple databases was underestimated"
      },
      {
        "title": "Directory Structure",
        "body": "docs/\n└── adr/\n    ├── README.md              # Index and guidelines\n    ├── template.md            # Team's ADR template\n    ├── 0001-use-postgresql.md\n    ├── 0002-caching-strategy.md\n    ├── 0003-mongodb-user-profiles.md  # [DEPRECATED]\n    └── 0020-deprecate-mongodb.md      # Supersedes 0003"
      },
      {
        "title": "ADR Index (README.md)",
        "body": "# Architecture Decision Records\n\n| ADR | Title | Status | Date |\n|-----|-------|--------|------|\n| [0001](0001-use-postgresql.md) | Use PostgreSQL | Accepted | 2024-01-10 |\n| [0002](0002-caching-strategy.md) | Caching with Redis | Accepted | 2024-01-12 |\n| [0003](0003-mongodb-user-profiles.md) | MongoDB for Profiles | Deprecated | 2023-06-15 |\n| [0020](0020-deprecate-mongodb.md) | Deprecate MongoDB | Accepted | 2024-01-15 |\n\n## Creating a New ADR\n1. Copy `template.md` to `NNNN-title-with-dashes.md`\n2. Fill in template, submit PR for review\n3. Update this index after approval"
      },
      {
        "title": "Tooling: adr-tools",
        "body": "# Install\nbrew install adr-tools\n\n# Initialize\nadr init docs/adr\n\n# Create new ADR\nadr new \"Use PostgreSQL as Primary Database\"\n\n# Supersede an ADR\nadr new -s 3 \"Deprecate MongoDB in Favor of PostgreSQL\"\n\n# Generate index\nadr generate toc > docs/adr/README.md"
      },
      {
        "title": "Review Checklist",
        "body": "Before submission:\n\nContext clearly explains the problem\n All viable options considered\n Pros/cons balanced and honest\n Consequences documented (positive AND negative)\n\nDuring review:\n\nAt least 2 senior engineers reviewed\n Affected teams consulted\n Security implications considered\n Reversibility assessed\n\nAfter acceptance:\n\nIndex updated\n Team notified\n Implementation tickets created"
      },
      {
        "title": "NEVER",
        "body": "Modify accepted ADRs: Write new ones to supersede\nSkip context: Future readers need the \"why\"\nHide failures: Rejected decisions are valuable learning\nBe vague: Specific decisions, specific consequences\nForget implementation: ADR without action is waste\nOver-document: Keep to 1-2 pages max\nDocument too late: Write BEFORE implementation starts"
      }
    ],
    "body": "Architecture Decision Records (ADRs)\nWHAT\n\nLightweight documentation capturing the context, decision, and consequences of significant technical choices. ADRs become the institutional memory of why things are built the way they are.\n\nWHEN\nAdopting new frameworks or technologies\nChoosing between architectural approaches\nMaking database or infrastructure decisions\nDefining API design patterns\nAny decision that would be hard to reverse or understand later\nKEYWORDS\n\nADR, architecture decision record, technical documentation, decision log, MADR, RFC, design decisions, trade-offs\n\nQuick Decision: Should I Write an ADR?\nWrite ADR\tSkip ADR\nNew framework/language adoption\tMinor version upgrades\nDatabase technology choice\tBug fixes\nAPI design patterns\tImplementation details\nSecurity architecture\tRoutine maintenance\nIntegration patterns\tConfiguration changes\nBreaking changes\tCode formatting\nADR Lifecycle\nProposed → Accepted → Deprecated → Superseded\n              ↓\n           Rejected\n\n\nNever modify accepted ADRs - write new ones to supersede.\n\nTemplates\nTemplate 1: Standard (Copy This)\n# ADR-NNNN: [Title]\n\n## Status\n[Proposed | Accepted | Deprecated | Superseded by ADR-XXXX]\n\n## Context\n[What is the issue? What forces are at play? 2-3 paragraphs max.]\n\n## Decision\nWe will [decision statement].\n\n## Consequences\n\n### Positive\n- [Benefit 1]\n- [Benefit 2]\n\n### Negative\n- [Drawback 1]\n- [Drawback 2]\n\n### Risks\n- [Risk and mitigation]\n\n## Related\n- ADR-XXXX: [Related decision]\n\nTemplate 2: Full (For Major Decisions)\n# ADR-0001: Use PostgreSQL as Primary Database\n\n## Status\nAccepted\n\n## Context\nWe need to select a primary database for our e-commerce platform handling:\n- ~10,000 concurrent users\n- Complex product catalog with hierarchical categories\n- Transaction processing for orders and payments\n- Full-text search for products\n\nThe team has experience with MySQL, PostgreSQL, and MongoDB.\n\n## Decision Drivers\n- **Must have** ACID compliance for payment processing\n- **Must support** complex queries for reporting  \n- **Should support** full-text search to reduce infrastructure\n- **Should have** good JSON support for flexible product attributes\n\n## Considered Options\n\n### Option 1: PostgreSQL\n**Pros**: ACID compliant, excellent JSONB support, built-in full-text search, PostGIS\n**Cons**: Slightly more complex replication than MySQL\n\n### Option 2: MySQL\n**Pros**: Familiar to team, simple replication\n**Cons**: Weaker JSON support, no built-in full-text search\n\n### Option 3: MongoDB\n**Pros**: Flexible schema, native JSON\n**Cons**: No ACID for multi-document transactions, team has limited experience\n\n## Decision\nWe will use **PostgreSQL 15** as our primary database.\n\n## Rationale\nPostgreSQL provides the best balance of ACID compliance (essential for e-commerce), \nbuilt-in capabilities (reduces infrastructure), and team familiarity.\n\n## Consequences\n\n### Positive\n- Single database handles transactions, search, and geospatial\n- Reduced operational complexity\n- Strong consistency for financial data\n\n### Negative\n- Need PostgreSQL-specific training for team\n- Vertical scaling limits may require read replicas\n\n### Risks\n- Full-text search may not scale as well as Elasticsearch\n- **Mitigation**: Design for potential ES addition if needed\n\n## Implementation Notes\n- Use JSONB for flexible product attributes\n- Implement connection pooling with PgBouncer\n- Set up streaming replication for read replicas\n\n## Related\n- ADR-0002: Caching Strategy (Redis)\n- ADR-0005: Search Architecture\n\nTemplate 3: Lightweight (For Smaller Decisions)\n# ADR-0012: Adopt TypeScript for Frontend\n\n**Status**: Accepted  \n**Date**: 2024-01-15  \n**Deciders**: @alice, @bob\n\n## Context\nReact codebase has 50+ components with increasing bugs from prop type mismatches.\n\n## Decision\nAdopt TypeScript for all new frontend code. Migrate existing code incrementally.\n\n## Consequences\n**Good**: Catch type errors at compile time, better IDE support  \n**Bad**: Learning curve, initial slowdown  \n**Mitigation**: Training sessions, `allowJs: true` for gradual adoption\n\nTemplate 4: Y-Statement (One-Liner)\n# ADR-0015: API Gateway Selection\n\nIn the context of **building a microservices architecture**,\nfacing **the need for centralized API management and rate limiting**,\nwe decided for **Kong Gateway**\nand against **AWS API Gateway and custom Nginx**,\nto achieve **vendor independence and plugin extensibility**,\naccepting that **we need to manage Kong infrastructure ourselves**.\n\nTemplate 5: Deprecation ADR\n# ADR-0020: Deprecate MongoDB in Favor of PostgreSQL\n\n## Status\nAccepted (Supersedes ADR-0003)\n\n## Context\nADR-0003 (2021) chose MongoDB for user profiles. Since then:\n- MongoDB transactions remain problematic for our use case\n- Our schema has stabilized and rarely changes\n- Maintaining two databases increases operational burden\n\n## Decision\nDeprecate MongoDB and migrate user profiles to PostgreSQL.\n\n## Migration Plan\n1. **Week 1-2**: Create PostgreSQL schema, enable dual-write\n2. **Week 3-4**: Backfill historical data, validate consistency\n3. **Week 5**: Switch reads to PostgreSQL\n4. **Week 6**: Remove MongoDB writes, decommission\n\n## Lessons Learned\n- Schema flexibility benefits were overestimated\n- Operational cost of multiple databases was underestimated\n\nDirectory Structure\ndocs/\n└── adr/\n    ├── README.md              # Index and guidelines\n    ├── template.md            # Team's ADR template\n    ├── 0001-use-postgresql.md\n    ├── 0002-caching-strategy.md\n    ├── 0003-mongodb-user-profiles.md  # [DEPRECATED]\n    └── 0020-deprecate-mongodb.md      # Supersedes 0003\n\nADR Index (README.md)\n# Architecture Decision Records\n\n| ADR | Title | Status | Date |\n|-----|-------|--------|------|\n| [0001](0001-use-postgresql.md) | Use PostgreSQL | Accepted | 2024-01-10 |\n| [0002](0002-caching-strategy.md) | Caching with Redis | Accepted | 2024-01-12 |\n| [0003](0003-mongodb-user-profiles.md) | MongoDB for Profiles | Deprecated | 2023-06-15 |\n| [0020](0020-deprecate-mongodb.md) | Deprecate MongoDB | Accepted | 2024-01-15 |\n\n## Creating a New ADR\n1. Copy `template.md` to `NNNN-title-with-dashes.md`\n2. Fill in template, submit PR for review\n3. Update this index after approval\n\nTooling: adr-tools\n# Install\nbrew install adr-tools\n\n# Initialize\nadr init docs/adr\n\n# Create new ADR\nadr new \"Use PostgreSQL as Primary Database\"\n\n# Supersede an ADR\nadr new -s 3 \"Deprecate MongoDB in Favor of PostgreSQL\"\n\n# Generate index\nadr generate toc > docs/adr/README.md\n\nReview Checklist\n\nBefore submission:\n\n Context clearly explains the problem\n All viable options considered\n Pros/cons balanced and honest\n Consequences documented (positive AND negative)\n\nDuring review:\n\n At least 2 senior engineers reviewed\n Affected teams consulted\n Security implications considered\n Reversibility assessed\n\nAfter acceptance:\n\n Index updated\n Team notified\n Implementation tickets created\nNEVER\nModify accepted ADRs: Write new ones to supersede\nSkip context: Future readers need the \"why\"\nHide failures: Rejected decisions are valuable learning\nBe vague: Specific decisions, specific consequences\nForget implementation: ADR without action is waste\nOver-document: Keep to 1-2 pages max\nDocument too late: Write BEFORE implementation starts"
  },
  "trust": {
    "sourceLabel": "tencent",
    "provenanceUrl": "https://clawhub.ai/wpank/architecture-decision-records",
    "publisherUrl": "https://clawhub.ai/wpank/architecture-decision-records",
    "owner": "wpank",
    "version": "1.0.0",
    "license": null,
    "verificationStatus": "Indexed source record"
  },
  "links": {
    "detailUrl": "https://openagent3.xyz/skills/architecture-decision-records",
    "downloadUrl": "https://openagent3.xyz/downloads/architecture-decision-records",
    "agentUrl": "https://openagent3.xyz/skills/architecture-decision-records/agent",
    "manifestUrl": "https://openagent3.xyz/skills/architecture-decision-records/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/architecture-decision-records/agent.md"
  }
}