Skip to main content
ArcKit uses document templates to generate consistent architecture artifacts. You can customize these templates without modifying the defaults, and your customizations will be preserved across updates.

​
How Template Customization Works

ArcKit uses a two-tier template system:
  1. Default templates live in .arckit/templates/ (refreshed by arckit init)
  2. Your customizations go in .arckit/templates-custom/ (preserved across updates)
  3. Commands automatically check for custom templates first, falling back to defaults
This pattern ensures:
  • Your customizations are preserved when upgrading ArcKit
  • Default templates can be updated without losing your changes
  • Easy to see what you’ve customized vs defaults

​
The /arckit.customize Command

​
Copy a Specific Template

/arckit.customize requirements
This copies the requirements template to .arckit/templates-custom/requirements-template.md for editing.

​
Copy All Templates

/arckit.customize all
Copies all 80+ templates to your customizations directory.

​
List Available Templates

/arckit.customize list
Shows all available templates with their corresponding commands.

​
Template Info

/arckit.customize info requirements
Shows what a template contains and common customization points.

​
Template Loading Logic

When you run an ArcKit command (e.g., /arckit.requirements):
  1. Command checks: Does .arckit/templates-custom/requirements-template.md exist?
  2. If YES → Uses YOUR customized template
  3. If NO → Uses default from .arckit/templates/

​
Common Customizations

​
Remove UK Government Sections

For non-UK Gov projects: 
<!-- Delete these sections -->
## UK Government Alignment
### Technology Code of Practice (TCoP)
### GDS Service Standard
### NCSC Cloud Security Principles

​
Change Document Control Fields

Add organization-specific fields: 
| **Cost Centre** | [YOUR_COST_CENTRE] |
| **Programme** | [PROGRAMME_NAME] |
| **Budget Code** | [BUDGET_CODE] |

​
Modify Requirement Prefixes

Change from BR/FR/NFR to your organization’s taxonomy: 
<!-- Before -->
**BR-001**: User Management
**FR-001**: User Registration
**NFR-001**: Response Time

<!-- After -->
**BUS-001**: User Management
**FUNC-001**: User Registration
**PERF-001**: Response Time

​
Update Priority Levels

Change MoSCoW to your framework: 
<!-- Before -->
Priority: Must Have / Should Have / Could Have / Won't Have

<!-- After -->
Priority: P1 (Critical) / P2 (High) / P3 (Medium) / P4 (Low)

​
Add Organization Branding

<!-- Add to header -->
![Company Logo](../assets/logo.png)

---
**CONFIDENTIAL - [COMPANY NAME]**
---

​
Customize Classification Banners

<!-- UK Government -->
**Classification**: OFFICIAL-SENSITIVE

<!-- Corporate -->
**Classification**: Company Confidential

<!-- Healthcare -->
**Classification**: Protected Health Information (PHI)

​
Customizing the Pages Template

The pages-template.html generates a documentation website. Common customizations:

​
Change Styling

<!-- Replace GOV.UK Design System with neutral colors -->
<style>
  :root {
    --primary: #0066cc;      /* Your brand blue */
    --secondary: #00cc66;    /* Your brand green */
    --accent: #ff6600;       /* Your brand orange */
  }
</style>

​
Remove UK-Specific Sections

<!-- Delete this section -->
<div class="category">
  <h3>UK Government</h3>
  <ul>
    <li><a href="#...">TCoP Assessment</a></li>
    <li><a href="#...">Service Standard</a></li>
  </ul>
</div>

<!-- Replace header -->
<header>
  <img src="/assets/logo.png" alt="Company Logo" />
  <h1>Architecture Documentation</h1>
</header>

<footer>
  <p>&copy; 2025 [Your Organization]. All rights reserved.</p>
  <p><a href="/terms">Terms</a> | <a href="/privacy">Privacy</a></p>
</footer>

​
Keeping Templates Updated

When ArcKit releases new template features:

​
Compare Your Template with Default

  1. Your custom template: .arckit/templates-custom/requirements-template.md
  2. New default template: .arckit/templates/requirements-template.md
  3. Use a diff tool to see what changed:
diff .arckit/templates/requirements-template.md \
     .arckit/templates-custom/requirements-template.md

​
Selective Adoption

You don’t have to adopt all changes. Cherry-pick what’s valuable:
  • New compliance sections: Copy if relevant to your industry
  • New requirement types: Adopt if your projects need them
  • Updated formatting: Adopt if it improves clarity
  • UK Gov specifics: Skip if not applicable

​
Reverting to Default

To stop using a custom template: 
rm .arckit/templates-custom/requirements-template.md
The command will now use the default template again.

​
Real-World Examples

​
Financial Services

Customization: Add PCI-DSS compliance section 
## PCI-DSS Compliance

### Requirement 1: Install and Maintain Network Security Controls
- Firewall rules documented: [YES/NO]
- Network segmentation enforced: [YES/NO]

### Requirement 3: Protect Stored Account Data
- Cardholder data encrypted: [YES/NO]
- Encryption standard: AES-256

​
Healthcare (US)

Customization: Add HIPAA compliance 
## HIPAA Compliance

### Administrative Safeguards
- Risk assessment completed: [YES/NO]
- Security officer assigned: [NAME]

### Physical Safeguards
- Facility access controls: [DESCRIBE]
- Workstation security: [DESCRIBE]

### Technical Safeguards
- Access controls: [DESCRIBE]
- Audit controls: [DESCRIBE]
- Encryption: AES-256 in transit and at rest

​
Manufacturing (Automotive)

Customization: Add ISO 26262 (functional safety) 
## ISO 26262 Functional Safety

### ASIL Rating
- Safety Goal: [DESCRIBE]
- ASIL Level: [A/B/C/D]

### Safety Requirements
- Fault detection: [DESCRIBE]
- Fault handling: [DESCRIBE]
- Redundancy: [DESCRIBE]

​
Defense/Government

Customization: Add clearance and classification 
## Security Classification

**Classification**: SECRET // REL TO USA, GBR, CAN, AUS, NZL
**Clearance Required**: SECRET with SC eligibility
**Handling Caveats**: NOFORN, ORCON

## MOD JSP 440 Compliance
- Security Operating Procedures (SyOPs): [REFERENCE]
- IAMM Level: [1/2/3/4/5]

​
Template Versioning

Custom templates inherit version numbers from the defaults: 
> **Template Origin**: Custom | **Based On**: `/arckit.requirements` | **ArcKit Version**: 3.0.9
This helps track:
  • Which default version your customization is based on
  • When to review for updates
  • Whether breaking changes have occurred

​
Best Practices

​
1. Start Small

Don’t customize everything at once. Start with your most-used templates:
  • Requirements (requirements-template.md)
  • Risk Register (risk-register-template.md)
  • Architecture Principles (architecture-principles-template.md)

​
2. Document Your Changes

Add a note at the top of custom templates: 
<!--
CUSTOMIZATIONS:
- Added ISO 27001 compliance section
- Removed UK Government alignment
- Changed requirement prefixes (BR → BUS, FR → FUNC)
- Updated with v3.0.9 defaults on 2025-01-15
-->

​
3. Version Control

Commit custom templates to git: 
git add .arckit/templates-custom/
git commit -m "Customize requirements template for ISO 27001"

​
4. Review Quarterly

Set a calendar reminder to check for template updates:
  1. Check ArcKit release notes
  2. Compare your custom templates with new defaults
  3. Adopt useful changes selectively

​
5. Share Across Projects

If you have multiple ArcKit projects: 
# Copy customizations to new project
cp -r old-project/.arckit/templates-custom/* \
       new-project/.arckit/templates-custom/

​
Troubleshooting

​
Command Not Using My Custom Template

Symptom: Command generates document from default template Causes:
  1. Filename mismatch (check spelling and hyphens)
  2. Template in wrong directory (must be .arckit/templates-custom/)
  3. Template has wrong extension (must be .md for markdown, .html for HTML)
Fix: 
# Check filename
ls .arckit/templates-custom/requirements-template.md

# Should match exactly (case-sensitive)

​
Template Validation Errors

Symptom: Command fails with “Template validation failed” Causes:
  1. Missing required placeholders (e.g., [PROJECT_ID], [VERSION])
  2. Invalid markdown syntax
  3. Broken document control section
Fix: Compare with default template to ensure all required fields present.

​
Custom Template Out of Date

Symptom: Generated documents missing new features Fix:
  1. Check CHANGELOG.md for template changes
  2. Diff your custom template against new default
  3. Manually merge new sections you want to keep

​
Further Reading

Build docs developers (and LLMs) love

Get started for freeTalk to us