# Send Architecture Decision Records to your agent Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually. ## Fast path - 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. ## Suggested prompts ### New install ```text 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. ``` ### Upgrade existing ```text 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. ``` ## Machine-readable fields ```json { "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": { "downloadUrl": "/downloads/architecture-decision-records", "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=architecture-decision-records", "sourcePlatform": "tencent", "targetPlatform": "OpenClaw", "packageFormat": "ZIP package", "primaryDoc": "SKILL.md", "includedAssets": [ "README.md", "SKILL.md" ], "downloadMode": "redirect", "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." ] } }, "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" } } ``` ## Documentation ### WHAT 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. ### WHEN Adopting new frameworks or technologies Choosing between architectural approaches Making database or infrastructure decisions Defining API design patterns Any decision that would be hard to reverse or understand later ### KEYWORDS ADR, architecture decision record, technical documentation, decision log, MADR, RFC, design decisions, trade-offs ### Quick Decision: Should I Write an ADR? Write ADRSkip ADRNew framework/language adoptionMinor version upgradesDatabase technology choiceBug fixesAPI design patternsImplementation detailsSecurity architectureRoutine maintenanceIntegration patternsConfiguration changesBreaking changesCode formatting ### ADR Lifecycle Proposed → Accepted → Deprecated → Superseded ↓ Rejected Never modify accepted ADRs - write new ones to supersede. ### Template 1: Standard (Copy This) # ADR-NNNN: [Title] ## Status [Proposed | Accepted | Deprecated | Superseded by ADR-XXXX] ## Context [What is the issue? What forces are at play? 2-3 paragraphs max.] ## Decision We will [decision statement]. ## Consequences ### Positive - [Benefit 1] - [Benefit 2] ### Negative - [Drawback 1] - [Drawback 2] ### Risks - [Risk and mitigation] ## Related - ADR-XXXX: [Related decision] ### Template 2: Full (For Major Decisions) # ADR-0001: Use PostgreSQL as Primary Database ## Status Accepted ## Context We need to select a primary database for our e-commerce platform handling: - ~10,000 concurrent users - Complex product catalog with hierarchical categories - Transaction processing for orders and payments - Full-text search for products The team has experience with MySQL, PostgreSQL, and MongoDB. ## Decision Drivers - **Must have** ACID compliance for payment processing - **Must support** complex queries for reporting - **Should support** full-text search to reduce infrastructure - **Should have** good JSON support for flexible product attributes ## Considered Options ### Option 1: PostgreSQL **Pros**: ACID compliant, excellent JSONB support, built-in full-text search, PostGIS **Cons**: Slightly more complex replication than MySQL ### Option 2: MySQL **Pros**: Familiar to team, simple replication **Cons**: Weaker JSON support, no built-in full-text search ### Option 3: MongoDB **Pros**: Flexible schema, native JSON **Cons**: No ACID for multi-document transactions, team has limited experience ## Decision We will use **PostgreSQL 15** as our primary database. ## Rationale PostgreSQL provides the best balance of ACID compliance (essential for e-commerce), built-in capabilities (reduces infrastructure), and team familiarity. ## Consequences ### Positive - Single database handles transactions, search, and geospatial - Reduced operational complexity - Strong consistency for financial data ### Negative - Need PostgreSQL-specific training for team - Vertical scaling limits may require read replicas ### Risks - Full-text search may not scale as well as Elasticsearch - **Mitigation**: Design for potential ES addition if needed ## Implementation Notes - Use JSONB for flexible product attributes - Implement connection pooling with PgBouncer - Set up streaming replication for read replicas ## Related - ADR-0002: Caching Strategy (Redis) - ADR-0005: Search Architecture ### Template 3: Lightweight (For Smaller Decisions) # ADR-0012: Adopt TypeScript for Frontend **Status**: Accepted **Date**: 2024-01-15 **Deciders**: @alice, @bob ## Context React codebase has 50+ components with increasing bugs from prop type mismatches. ## Decision Adopt TypeScript for all new frontend code. Migrate existing code incrementally. ## Consequences **Good**: Catch type errors at compile time, better IDE support **Bad**: Learning curve, initial slowdown **Mitigation**: Training sessions, \`allowJs: true\` for gradual adoption ### Template 4: Y-Statement (One-Liner) # ADR-0015: API Gateway Selection In the context of **building a microservices architecture**, facing **the need for centralized API management and rate limiting**, we decided for **Kong Gateway** and against **AWS API Gateway and custom Nginx**, to achieve **vendor independence and plugin extensibility**, accepting that **we need to manage Kong infrastructure ourselves**. ### Template 5: Deprecation ADR # ADR-0020: Deprecate MongoDB in Favor of PostgreSQL ## Status Accepted (Supersedes ADR-0003) ## Context ADR-0003 (2021) chose MongoDB for user profiles. Since then: - MongoDB transactions remain problematic for our use case - Our schema has stabilized and rarely changes - Maintaining two databases increases operational burden ## Decision Deprecate MongoDB and migrate user profiles to PostgreSQL. ## Migration Plan 1. **Week 1-2**: Create PostgreSQL schema, enable dual-write 2. **Week 3-4**: Backfill historical data, validate consistency 3. **Week 5**: Switch reads to PostgreSQL 4. **Week 6**: Remove MongoDB writes, decommission ## Lessons Learned - Schema flexibility benefits were overestimated - Operational cost of multiple databases was underestimated ### Directory Structure docs/ └── adr/ ├── README.md # Index and guidelines ├── template.md # Team's ADR template ├── 0001-use-postgresql.md ├── 0002-caching-strategy.md ├── 0003-mongodb-user-profiles.md # [DEPRECATED] └── 0020-deprecate-mongodb.md # Supersedes 0003 ### ADR Index (README.md) # Architecture Decision Records | ADR | Title | Status | Date | |-----|-------|--------|------| | [0001](0001-use-postgresql.md) | Use PostgreSQL | Accepted | 2024-01-10 | | [0002](0002-caching-strategy.md) | Caching with Redis | Accepted | 2024-01-12 | | [0003](0003-mongodb-user-profiles.md) | MongoDB for Profiles | Deprecated | 2023-06-15 | | [0020](0020-deprecate-mongodb.md) | Deprecate MongoDB | Accepted | 2024-01-15 | ## Creating a New ADR 1. Copy \`template.md\` to \`NNNN-title-with-dashes.md\` 2. Fill in template, submit PR for review 3. Update this index after approval ### Tooling: adr-tools # Install brew install adr-tools # Initialize adr init docs/adr # Create new ADR adr new "Use PostgreSQL as Primary Database" # Supersede an ADR adr new -s 3 "Deprecate MongoDB in Favor of PostgreSQL" # Generate index adr generate toc > docs/adr/README.md ### Review Checklist Before submission: Context clearly explains the problem All viable options considered Pros/cons balanced and honest Consequences documented (positive AND negative) During review: At least 2 senior engineers reviewed Affected teams consulted Security implications considered Reversibility assessed After acceptance: Index updated Team notified Implementation tickets created ### NEVER Modify accepted ADRs: Write new ones to supersede Skip context: Future readers need the "why" Hide failures: Rejected decisions are valuable learning Be vague: Specific decisions, specific consequences Forget implementation: ADR without action is waste Over-document: Keep to 1-2 pages max Document too late: Write BEFORE implementation starts ## Trust - Source: tencent - Verification: Indexed source record - Publisher: wpank - Version: 1.0.0 ## Source health - Status: healthy - Source download looks usable. - Yavira can redirect you to the upstream package for this source. - Health scope: source - Reason: direct_download_ok - Checked at: 2026-04-23T16:43:11.935Z - Expires at: 2026-04-30T16:43:11.935Z - Recommended action: Download for OpenClaw ## Links - [Detail page](https://openagent3.xyz/skills/architecture-decision-records) - [Send to Agent page](https://openagent3.xyz/skills/architecture-decision-records/agent) - [JSON manifest](https://openagent3.xyz/skills/architecture-decision-records/agent.json) - [Markdown brief](https://openagent3.xyz/skills/architecture-decision-records/agent.md) - [Download page](https://openagent3.xyz/downloads/architecture-decision-records)