Architecture Decision Record

Καταγραφή αρχιτεκτονικής απόφασης (ADR)

Πρότυπα, παραδείγματα και καθοδήγηση για την καταγραφή αρχιτεκτονικών αποφάσεων.

Μια καταγραφή αρχιτεκτονικής απόφασης (ADR) είναι ένα έγγραφο που καταγράφει μια σημαντική αρχιτεκτονική απόφαση που ελήφθη, μαζί με το πλαίσιο και τις συνέπειές της.

Μεταφράσεις: العربية, বাংলা, Cymraeg, Dansk, Deutsch, English, Ελληνικά, Română, Polski, Español, Eesti, Suomi, Français, हिन्दी, Bahasa Indonesia, Íslenska, Italiano, 日本語, 한국어, Nederlands, Português, Русский, Svenska, Kiswahili, ไทย, Türkçe, اردو, Tiếng Việt, 中文

Κάντε τη δική σας δέουσα επιμέλεια για αυτούς τους πόρους πριν τους χρησιμοποιήσετε σε οποιαδήποτε κρίσιμα συστήματα.

Περιεχόμενα:

Πρότυπα:

Παραδείγματα:

Τι είναι μια καταγραφή αρχιτεκτονικής απόφασης;

Μια καταγραφή αρχιτεκτονικής απόφασης (architecture decision record, ADR) είναι ένα έγγραφο που καταγράφει μια σημαντική αρχιτεκτονική απόφαση που ελήφθη, μαζί με το πλαίσιο και τις συνέπειές της.

Μια αρχιτεκτονική απόφαση (architecture decision, AD) είναι μια επιλογή σχεδίασης λογισμικού που ανταποκρίνεται σε μια σημαντική απαίτηση.

Ένα αρχείο καταγραφής αρχιτεκτονικών αποφάσεων (architecture decision log, ADL) είναι το σύνολο όλων των ADR που δημιουργούνται και συντηρούνται για ένα συγκεκριμένο έργο (ή οργανισμό).

Μια αρχιτεκτονικά σημαντική απαίτηση (architecturally-significant requirement, ASR) είναι μια απαίτηση που έχει μετρήσιμη επίδραση στην αρχιτεκτονική ενός συστήματος λογισμικού.

Όλα αυτά εντάσσονται στο αντικείμενο της διαχείρισης αρχιτεκτονικής γνώσης (architecture knowledge management, AKM).

Στόχος αυτού του εγγράφου είναι να παρέχει μια γρήγορη επισκόπηση των ADR, του τρόπου δημιουργίας τους και του πού μπορείτε να αναζητήσετε περισσότερες πληροφορίες.

Συντομογραφίες:

  • AD: αρχιτεκτονική απόφαση

  • ADL: αρχείο καταγραφής αρχιτεκτονικών αποφάσεων

  • ADR: καταγραφή αρχιτεκτονικής απόφασης

  • AKM: διαχείριση αρχιτεκτονικής γνώσης

  • ASR: αρχιτεκτονικά σημαντική απαίτηση

Πώς να ξεκινήσετε με τα ADR

Για να ξεκινήσετε να χρησιμοποιείτε ADR, συζητήστε με τους συναδέλφους σας τους παρακάτω τομείς.

Εντοπισμός αποφάσεων:

  • Πόσο επείγουσα και πόσο σημαντική είναι η αρχιτεκτονική απόφαση;

  • Πρέπει να ληφθεί τώρα ή μπορεί να περιμένει μέχρι να γίνουν γνωστά περισσότερα;

  • Τόσο η προσωπική και συλλογική εμπειρία όσο και οι αναγνωρισμένες μέθοδοι και πρακτικές σχεδίασης μπορούν να βοηθήσουν στον εντοπισμό αποφάσεων.

  • Ιδανικά, διατηρήστε μια λίστα αποφάσεων προς λήψη που συμπληρώνει τη λίστα εργασιών του προϊόντος.

Λήψη αποφάσεων:

  • Υπάρχουν πολλές τεχνικές λήψης αποφάσεων, τόσο γενικές όσο και ειδικές για την αρχιτεκτονική λογισμικού, για παράδειγμα η χαρτογράφηση διαλόγου (dialogue mapping).

  • Η ομαδική λήψη αποφάσεων είναι ενεργό θέμα έρευνας.

Εφαρμογή και επιβολή αποφάσεων:

  • Οι αρχιτεκτονικές αποφάσεις χρησιμοποιούνται στη σχεδίαση λογισμικού· γι' αυτό πρέπει να κοινοποιούνται και να γίνονται αποδεκτές από τα ενδιαφερόμενα μέρη του συστήματος που το χρηματοδοτούν, το αναπτύσσουν και το λειτουργούν.

  • Τα στυλ κωδικοποίησης όπου η αρχιτεκτονική είναι εμφανής και οι αναθεωρήσεις κώδικα που εστιάζουν σε αρχιτεκτονικά ζητήματα και αποφάσεις είναι δύο σχετικές πρακτικές.

  • Οι αρχιτεκτονικές αποφάσεις πρέπει επίσης να (επανα)εξετάζονται κατά τον εκσυγχρονισμό ενός συστήματος λογισμικού στο πλαίσιο της εξέλιξής του.

Κοινοποίηση αποφάσεων (προαιρετικά):

  • Πολλές αρχιτεκτονικές αποφάσεις επαναλαμβάνονται σε διαφορετικά έργα.

  • Συνεπώς, οι εμπειρίες από προηγούμενες αποφάσεις, καλές ή κακές, μπορούν να αποτελέσουν πολύτιμο επαναχρησιμοποιήσιμο κεφάλαιο όταν εφαρμόζεται μια ρητή στρατηγική διαχείρισης γνώσης.

Τεκμηρίωση αποφάσεων:

  • Υπάρχουν πολλά πρότυπα και εργαλεία για την καταγραφή αποφάσεων.

  • Δείτε τις ευέλικτες κοινότητες, π.χ. τα ADR του M. Nygard.

  • Δείτε τις παραδοσιακές διαδικασίες μηχανικής λογισμικού και σχεδίασης αρχιτεκτονικής, π.χ. τις διατάξεις πινάκων που προτείνονται από την IBM UMF και από τους Tyree και Akerman της CapitalOne.

Για περισσότερα:

  • Τα παραπάνω βήματα προέρχονται από το λήμμα της Wikipedia Architectural Decision

Πώς να ξεκινήσετε με τα ADR και εργαλεία

  • MySpec — Αυτοματοποιημένη πλατφόρμα προδιαγραφών και αρχιτεκτονικών αποφάσεων που οργανώνει το καταστατικό του έργου, την τεχνική αρχιτεκτονική και τα ADR σε καθαρό Markdown που παρέχεται μέσω MCP.

Μπορείτε να ξεκινήσετε να χρησιμοποιείτε ADR με εργαλεία με όποιον τρόπο θέλετε.

Για παράδειγμα:

  • Αν σας αρέσει το Google Drive και η επεξεργασία στο διαδίκτυο, μπορείτε να δημιουργήσετε ένα Έγγραφο Google ή ένα Υπολογιστικό Φύλλο Google.

  • Αν σας αρέσει ο έλεγχος εκδόσεων του πηγαίου κώδικα, όπως το git, μπορείτε να δημιουργήσετε ένα αρχείο για κάθε ADR.

  • Αν σας αρέσουν τα εργαλεία σχεδιασμού έργων, όπως το Atlassian Jira, μπορείτε να χρησιμοποιήσετε το εργαλείο παρακολούθησης σχεδιασμού του.

  • Αν σας αρέσουν τα wiki, όπως το MediaWiki, μπορείτε να δημιουργήσετε ένα wiki για ADR.

Πώς να ξεκινήσετε με τα ADR και το git

Αν σας αρέσει ο έλεγχος εκδόσεων με το git, ορίστε πώς μας αρέσει να ξεκινάμε με ADR και git σε ένα τυπικό έργο λογισμικού με πηγαίο κώδικα.

Δημιουργήστε έναν κατάλογο για τα αρχεία ADR:

$ mkdir adr

Για κάθε ADR, δημιουργήστε ένα αρχείο κειμένου, όπως το choose-database.md:

$ vi choose-database.md

Γράψτε στο ADR ό,τι θέλετε. Δείτε τα πρότυπα σε αυτό το αποθετήριο για ιδέες.

Κάντε commit το ADR στο αποθετήριο git σας.

Δεξιότητες Claude Code για ADR

Αυτό το αποθετήριο περιλαμβάνει δύο δεξιότητες (skills) για το Claude Code στον κατάλογο skills/, ώστε ένας πράκτορας προγραμματισμού AI να μπορεί να γράφει και να συντηρεί ADR με τον τρόπο που προτείνει αυτό το έργο:

  • architecture-decision-record-skill — γενικής χρήσης, για οποιονδήποτε γράφει ένα ADR σε οποιοδήποτε έργο. Βοηθά να αποφασιστεί αν μια απόφαση χρειάζεται ADR, δημιουργεί κατάλογο adr/ ή decisions/, ονομάζει το αρχείο, επιλέγει πρότυπο από τους έντεκα συνοδευτικούς σκελετούς και γράφει στιβαρές ενότητες Πλαίσιο/Απόφαση/Συνέπειες.

  • architecture-decision-record-maintainer-skill — ειδικά για τους συντηρητές αυτού του αποθετηρίου. Τεκμηριώνει τη διάταξη του αποθετηρίου, τη σύμβαση κατοπτρισμού README/locales και τα ακριβή βήματα για την προσθήκη νέου προτύπου, παραδείγματος ή συνδέσμου εργαλείου.

Για να χρησιμοποιήσετε μια δεξιότητα, αντιγράψτε τον φάκελό της στο .claude/skills/ στη ρίζα του αποθετηρίου όπου εργάζεστε (ή στο ~/.claude/skills/ για να είναι διαθέσιμη σε κάθε έργο) και έπειτα ζητήστε από το Claude Code να γράψει ή να αναθεωρήσει ένα ADR.

Συμβάσεις ονομασίας αρχείων ADR

Αν επιλέξετε να δημιουργείτε τα ADR σας σε τυπικά αρχεία κειμένου, ίσως θέλετε να διαμορφώσετε τη δική σας σύμβαση ονομασίας αρχείων ADR.

Εμείς προτιμούμε μια σύμβαση ονομασίας αρχείων με συγκεκριμένη μορφή.

Παραδείγματα:

  • choose-database.md

  • format-timestamps.md

  • manage-passwords.md

  • handle-exceptions.md

Η σύμβαση ονομασίας αρχείων που ακολουθούμε:

  • Το όνομα περιέχει μια ρηματική φράση σε προστακτική (στα αγγλικά, ενεστώτας). Αυτό βελτιώνει την αναγνωσιμότητα και ταιριάζει με τη μορφή των μηνυμάτων commit μας.

  • Το όνομα χρησιμοποιεί πεζά γράμματα και παύλες (όπως και αυτό το αποθετήριο). Είναι μια ισορροπία ανάμεσα στην αναγνωσιμότητα και τη χρηστικότητα στο σύστημα.

  • Η επέκταση είναι markdown. Αυτό διευκολύνει τη μορφοποίηση.

Προτάσεις για τη συγγραφή καλών ADR

Χαρακτηριστικά ενός καλού ADR:

  • Αιτιολόγηση: Εξηγήστε τους λόγους για τους οποίους λαμβάνεται η συγκεκριμένη αρχιτεκτονική απόφαση. Αυτό μπορεί να περιλαμβάνει το πλαίσιο (βλ. παρακάτω), τα υπέρ και τα κατά των διαφόρων πιθανών επιλογών, συγκρίσεις χαρακτηριστικών, συζητήσεις κόστους/οφέλους και άλλα.

  • Συγκεκριμένο: Κάθε ADR πρέπει να αφορά μία αρχιτεκτονική απόφαση, όχι πολλές.

  • Χρονοσημάνσεις: Προσδιορίστε πότε γράφτηκε κάθε στοιχείο του ADR. Αυτό είναι ιδιαίτερα σημαντικό για πτυχές που μπορεί να αλλάξουν με την πάροδο του χρόνου, όπως το κόστος, τα χρονοδιαγράμματα, η κλιμάκωση και τα παρόμοια.

  • Αμετάβλητο: Μην αλλάζετε τις υπάρχουσες πληροφορίες σε ένα ADR. Αντίθετα, τροποποιήστε το ADR προσθέτοντας νέες πληροφορίες ή αντικαταστήστε το δημιουργώντας ένα νέο ADR.

Χαρακτηριστικά μιας καλής ενότητας «Πλαίσιο» σε ένα ADR:

  • Εξηγήστε την κατάσταση του οργανισμού σας και τις επιχειρηματικές προτεραιότητες.

  • Συμπεριλάβετε αιτιολόγηση και σκέψεις βάσει της κοινωνικής σύνθεσης και των δεξιοτήτων των ομάδων σας.

  • Συμπεριλάβετε τα σχετικά υπέρ και κατά και περιγράψτε τα με όρους που ευθυγραμμίζονται με τις ανάγκες και τους στόχους σας.

Χαρακτηριστικά μιας καλής ενότητας «Συνέπειες» σε ένα ADR:

  • Εξηγήστε τι προκύπτει από τη λήψη της απόφασης. Αυτό μπορεί να περιλαμβάνει τις επιπτώσεις, τα αποτελέσματα, τα παραγόμενα, τις ενέργειες παρακολούθησης και άλλα.

  • Συμπεριλάβετε πληροφορίες για τυχόν επόμενα ADR. Είναι σχετικά συνηθισμένο ένα ADR να προκαλεί την ανάγκη για περισσότερα ADR, για παράδειγμα όταν ένα ADR κάνει μια μεγάλη υπερκαλύπτουσα επιλογή, η οποία με τη σειρά της δημιουργεί ανάγκες για περισσότερες μικρότερες αποφάσεις.

  • Συμπεριλάβετε τυχόν διαδικασίες αναθεώρησης μετά τη δράση. Είναι τυπικό οι ομάδες να αναθεωρούν κάθε ADR έναν μήνα αργότερα, για να συγκρίνουν τις πληροφορίες του ADR με ό,τι συνέβη στην πράξη, ώστε να μάθουν και να εξελιχθούν.

Ένα νέο ADR μπορεί να αντικαταστήσει ένα προηγούμενο ADR:

  • Όταν λαμβάνεται μια αρχιτεκτονική απόφαση που αντικαθιστά ή ακυρώνει ένα προηγούμενο ADR, πρέπει να δημιουργηθεί ένα νέο ADR

Πρότυπα παραδείγματα ADR

Πρότυπα παραδείγματα ADR που συλλέξαμε στο διαδίκτυο:

Συμβουλές ομαδικής εργασίας για ADR

Αν σκέφτεστε να χρησιμοποιήσετε καταγραφές αποφάσεων με την ομάδα σας, ορίστε μερικές συμβουλές που μάθαμε δουλεύοντας με πολλές ομάδες.

Έχετε την ευκαιρία να καθοδηγήσετε τους συναδέλφους σας, συζητώντας μαζί για το «γιατί», αντί να επιβάλλετε το «τι». Για παράδειγμα, οι καταγραφές αποφάσεων είναι ένας τρόπος για να σκέφτονται πιο έξυπνα και να επικοινωνούν καλύτερα οι ομάδες· οι καταγραφές αποφάσεων δεν έχουν αξία αν είναι απλώς μια αναγκαστική γραφειοκρατική απαίτηση εκ των υστέρων.

Ορισμένες ομάδες προτιμούν πολύ το όνομα «αποφάσεις» αντί της συντομογραφίας «ADR». Όταν κάποιες ομάδες χρησιμοποιούν το όνομα καταλόγου «decisions», είναι σαν να ανάβει μια λάμπα και η ομάδα αρχίζει να βάζει περισσότερες πληροφορίες στον κατάλογο, όπως αποφάσεις για προμηθευτές, αποφάσεις σχεδιασμού, αποφάσεις χρονοπρογραμματισμού κ.λπ. Όλα αυτά τα είδη πληροφοριών μπορούν να χρησιμοποιούν το ίδιο πρότυπο. Υποθέτουμε ότι οι άνθρωποι μαθαίνουν ταχύτερα με λέξεις («αποφάσεις») παρά με συντομογραφίες («ADR»), ότι έχουν περισσότερο κίνητρο να γράφουν έγγραφα σε εξέλιξη όταν αφαιρείται η λέξη «καταγραφή» και ότι ορισμένοι προγραμματιστές και ορισμένοι διευθυντές αντιπαθούν τη λέξη «αρχιτεκτονική».

Θεωρητικά, το αμετάβλητο είναι ιδανικό. Στην πράξη, η μεταβλητότητα έχει λειτουργήσει καλύτερα για τις ομάδες μας. Εισάγουμε τη νέα πληροφορία στο υπάρχον ADR, με ημερομηνία και μια σημείωση ότι η πληροφορία ήρθε μετά την απόφαση. Αυτή η προσέγγιση οδηγεί σε ένα «ζωντανό έγγραφο» που μπορούμε όλοι να ενημερώνουμε. Τυπικές ενημερώσεις γίνονται όταν λαμβάνουμε πληροφορίες χάρη σε νέους συναδέλφους, νέες προσφορές, πραγματικά αποτελέσματα της χρήσης μας ή αλλαγές τρίτων εκ των υστέρων, όπως δυνατότητες προμηθευτών, τιμολογιακά σχέδια, συμφωνίες αδειοδότησης κ.λπ.

Ερωτήσεις ομαδικής εργασίας για ADR

Ποιος μπορεί να δημιουργήσει ένα ADR;

Εξετάστε τομείς όπως συγκεκριμένα πρόσωπα, συγκεκριμένους ρόλους, συγκεκριμένες ομάδες ή συγκεκριμένα τμήματα· εξετάστε επίσης αν υπάρχουν πρόσωπα, ρόλοι, ομάδες ή τμήματα που μπορούν να αναθέσουν ένα ADR, δηλαδή να ζητήσουν να το συντάξει κάποιος άλλος.

Παράδειγμα απάντησης: Οποιοδήποτε πρόσωπο στον οργανισμό μας που έχει διαβάσει τη σελίδα README για την καταγραφή αρχιτεκτονικών αποφάσεων μπορεί να προτείνει ένα ADR, δηλαδή να αρχίσει να το γράφει και να το μοιραστεί με την ομάδα.

Τι δικαιολογεί τη δημιουργία ενός ADR;

Εξετάστε τομείς όπως οι τρόποι εργασίας των ομάδων του οργανισμού σας, η δομή του συστήματος λογισμικού σας, ο συντονισμός μεταξύ ομάδων, η μακροπρόθεσμη συντηρησιμότητα, οι εξωτερικές διεπαφές, ποιον θέλετε να ωφελήσετε και τα παρόμοια.

Παράδειγμα απάντησης: Θέλουμε να δημιουργούμε ένα ADR όταν θέλουμε οι μελλοντικοί προγραμματιστές να κατανοούν το «γιατί» αυτού που κάνουμε.

Τι δικαιολογεί τη μη δημιουργία ενός ADR;

Εξετάστε τομείς όπως αποφάσεις που δεν αφορούν την αρχιτεκτονική ή είναι μικροσκοπικές, π.χ. ελάχιστου ρίσκου ή αυτοτελείς ή ενός προγραμματιστή, ή καλύπτονται ήδη πλήρως αλλού, π.χ. από πρότυπα, πολιτικές ή τεκμηρίωση, ή είναι προσωρινές, π.χ. παρακάμψεις, αποδείξεις εννοίας ή πειράματα.

Παράδειγμα απάντησης: Παραλείπουμε ένα ADR όταν μια απόφαση είναι περιορισμένη σε εύρος, χρόνο, ρίσκο και κόστος ή καλύπτεται ήδη αλλού.

Ποιος είναι ο κύκλος ζωής ενός ADR;

Εξετάστε τομείς όπως η διαδικασία δημιουργίας, η διαδικασία έρευνας, η διαδικασία λήψης απόφασης, η διαδικασία υλοποίησης και η διαδικασία απόσυρσης. Εξετάστε πώς θα παρακολουθείτε τον κύκλο ζωής του ADR με την πάροδο του χρόνου, π.χ. πώς θα μετακινείτε το ADR από μια κατάσταση στην επόμενη και πώς θα το κοινοποιείτε στα ενδιαφερόμενα μέρη.

Παράδειγμα απάντησης: Θέλουμε ένα ADR να έχει πέντε στάδια κύκλου ζωής: Έναρξη → Έρευνα → Αξιολόγηση → Υλοποίηση → Συντήρηση → Απόσυρση.

Ποια είναι τα κριτήρια για τα στάδια του κύκλου ζωής ενός ADR;

Εξετάστε τομείς όπως τα κριτήρια αποδοχής ενός ADR, δηλαδή πώς ξέρετε ότι είναι αρκετά καλό για να προχωρήσει από ένα στάδιο του κύκλου ζωής στο επόμενο; Είναι το πρόβλημα σαφώς διατυπωμένο; Έχουν εξεταστεί οι εναλλακτικές; Είναι οι συμβιβασμοί αρκετά κατανοητοί και τεκμηριωμένοι; Υπάρχει όλο το σχετικό πλαίσιο; Συμμετέχουν όλα τα σχετικά ενδιαφερόμενα μέρη; Έχουν ενσωματωθεί όλα τα σχόλια;

Παράδειγμα απάντησης: Θέλουμε ένα ADR να τίθεται σε ψηφοφορία από τα ενδιαφερόμενα μέρη όταν η ενεργή ομάδα 1) έχει ολοκληρώσει την έρευνά της, 2) έχει ολοκληρώσει την αξιολόγησή της, 3) έχει δημοσιεύσει την πρόταση ADR στα ενδιαφερόμενα μέρη με αίτημα για σχόλια και χρονικό περιθώριο μίας εβδομάδας, 4) όλα τα σχόλια των ενδιαφερόμενων μερών έχουν ενσωματωθεί και αντιμετωπιστεί.

Ποιοι ρόλοι και ευθύνες αλληλεπιδρούν με ένα ADR;

Εξετάστε ρόλους όπως εισηγητής, ερευνητής, αξιολογητής, αναθεωρητής, εγκρίνων, συντηρητής και τα παρόμοια. Εξετάστε ευθύνες όπως η επικοινωνία με τα ενδιαφερόμενα μέρη, η διασφάλιση ότι ικανοποιούνται οι προσδοκίες, η κοινοποίηση στον ιστότοπο ή το ενδοδίκτυο και η περιοδική αναθεώρηση της εργασίας, ειδικά όταν συμβαίνουν σχετικές αλλαγές.

Παράδειγμα απάντησης: Θέλουμε κάθε ADR να έχει πάντα ένα κύριο πρόσωπο επαφής, ένα δευτερεύον πρόσωπο επαφής και μια υπεύθυνη ομάδα· αυτά είναι υπεύθυνα για τις επικοινωνίες, τις δημοσιεύσεις, τη συντήρηση, την περιοδική αναθεώρηση τουλάχιστον μία φορά τον χρόνο και την ενδεχόμενη απόσυρση όπου χρειάζεται.

Πώς αλληλεπιδρά η διακυβέρνηση με ένα ADR;

Εξετάστε τομείς όπως οι τρόποι εργασίας του οργανισμού σας, τυχόν ειδικές ανάγκες συμμόρφωσης, π.χ. νομικές πτυχές ή πτυχές ανθρώπινου δυναμικού, και πώς θέλετε να χειρίζεστε τη συναίνεση έναντι της σύγκρουσης έναντι της κλιμάκωσης. Υπάρχουν τομείς, πρόσωπα ή ομάδες που μπορούν να έχουν μεγαλύτερη επιρροή από άλλους σε ένα ADR, π.χ. να μπορούν να το εγκρίνουν, να ψηφίσουν γι' αυτό ή να του ασκήσουν βέτο;

Παράδειγμα απάντησης: Η διακυβέρνηση ενός ADR γίνεται με αυτή τη σειρά προτεραιότητας: ο CEO, ο CTO, ο CLO, η ομάδα που υλοποιεί ένα ADR, οι ειδικοί της ομάδας που γνωρίζουν καλύτερα την αρχιτεκτονική απόφαση. Κανείς άλλος δεν έχει διακυβέρνηση, εκτός αν περιγράφεται στο ADR.

Ποιες αρχές αλληλεπιδρούν με ένα ADR;

Εξετάστε τομείς όπως οι τρόποι εργασίας του οργανισμού σας που περιλαμβάνουν γρήγορη έναντι αργής κίνησης, συναίνεση έναντι σύγκρουσης στις αποφάσεις, προτιμήσεις ρίσκου έναντι προτιμήσεων ασφάλειας, δημόσια συζήτηση έναντι ιδιωτικής συζήτησης και τα παρόμοια.

Παράδειγμα απάντησης: Χρησιμοποιούμε τις αρχές ηγεσίας της προτίμησης στη δράση, της διαφωνίας και δέσμευσης (disagree-and-commit), των εκτιμήσεων 70% που είναι αρκετά καλές για εύκολα αναστρέψιμες και εύκολα απομονώσιμες αποφάσεις, και των δημόσιων τρόπων εργασίας με εξαίρεση τις εμπιστευτικές πληροφορίες, όπως περιγράφονται στη συμφωνία εμπιστευτικότητας του οργανισμού μας.

Έννοιες για το επόμενο βήμα των ADR

Το Arc42 απαντά πραγματιστικά σε δύο ερωτήματα και μπορεί να προσαρμοστεί στις ειδικές σας ανάγκες. Τι πρέπει να τεκμηριώσετε/κοινοποιήσετε για την αρχιτεκτονική σας; Πώς πρέπει να το τεκμηριώσετε/κοινοποιήσετε; Το Arc42 περιλαμβάνει καταγραφές αρχιτεκτονικών αποφάσεων καθώς και καθοδήγηση για στόχους, περιορισμούς, πλαίσια, ποιότητα, κινδύνους και άλλα.

Το μοντέλο C4 είναι μια εύκολη στην εκμάθηση, φιλική προς τους προγραμματιστές προσέγγιση στη διαγραμματική απεικόνιση αρχιτεκτονικής λογισμικού. Το C4 είναι ένα σύνολο ιεραρχικών διαγραμμάτων για πλαίσιο, κοντέινερ, στοιχεία, κώδικα, συν υποστηρικτικά διαγράμματα για το τοπίο συστημάτων, τη δυναμική και την ανάπτυξη.

Αρχιτεκτονικά διαγράμματα, όψεις και σκοπιές

Ένα αρχιτεκτονικό διάγραμμα ονομάζεται «αρχιτεκτονική όψη».

Μια «αρχιτεκτονική όψη» είναι ένα στιγμιότυπο μιας «αρχιτεκτονικής σκοπιάς».

Μια «αρχιτεκτονική σκοπιά» έχει συγκεκριμένο κοινό με συγκεκριμένες ανησυχίες στο μυαλό.

Παραδείγματα αρχιτεκτονικών σκοπιών, παραδείγματα όψεων και παραδείγματα διαγραμμάτων:

Σχετικά διαγράμματα:

  • Ένα Διάγραμμα Περιπτώσεων Χρήσης δείχνει τις περιπτώσεις χρήσης στη διοίκηση/τους πελάτες, κάτι που προηγείται των απαιτήσεων, που προηγούνται της αρχιτεκτονικής λογισμικού.

  • Ένα Διάγραμμα Ανάπτυξης δείχνει το φυσικό υλικό/τους υπολογιστές στους οποίους αναπτύσσονται τα στοιχεία λογισμικού.

  • Ένα Διάγραμμα Ροής Δεδομένων δείχνει πώς κινούνται τα δεδομένα μέσα στο σύστημα και πώς μετασχηματίζονται.

  • Ένα Διάγραμμα Ακολουθίας χρησιμοποιείται για να δείξει πώς λειτουργούν πρωτόκολλα όπως το HTTP σε άξονα χρόνου.

  • Ένα Διάγραμμα Δραστηριοτήτων απεικονίζει τη ροή εργασίας των δραστηριοτήτων που αναλαμβάνει ένα σύστημα λογισμικού, όπως μια ΤΝ μη παικτικού χαρακτήρα (NPC).

Συναρτήσεις καταλληλότητας για αποφάσεις ως κώδικα

Οι συναρτήσεις καταλληλότητας (fitness functions) είναι αντικειμενικοί αυτοματοποιημένοι έλεγχοι, γραμμένοι με κώδικα προγραμματισμού, που επαληθεύουν ότι οι αποφάσεις τηρούνται.

  • Οι συναρτήσεις καταλληλότητας κάνουν τις αποφάσεις ελέγξιμες και διασφαλίσιμες.

  • Οι συναρτήσεις καταλληλότητας για αποφάσεις μπορούν να βοηθήσουν σημαντικά στη διασφάλιση ποιότητας, στις ρυθμιστικές διαδικασίες και στους στόχους διακυβέρνησης.

Πώς συνδέονται οι συναρτήσεις καταλληλότητας με τις αποφάσεις

Μια καταγραφή απόφασης τεκμηριώνει την απόφαση, ενώ μια συνάρτηση καταλληλότητας τη διασφαλίζει.

  • Παράδειγμα απόφασης: Χρησιμοποιούμε event sourcing για τις απαιτήσεις ελέγχου (audit).

  • Παράδειγμα συνάρτησης καταλληλότητας: Χρησιμοποιούμε τον διακομιστή συνεχούς ολοκλήρωσης για να ελέγξουμε ότι κάθε αλλαγή κατάστασης πρέπει να παράγει γεγονότα.

Γιατί οι συναρτήσεις καταλληλότητας βοηθούν τις αποφάσεις

Αντικειμενικές μετρήσεις: Οι συναρτήσεις καταλληλότητας περνούν ή αποτυγχάνουν, οπότε η εργασία είναι ορατή και σαφής.

Συνεχής χρήση: Οι συναρτήσεις καταλληλότητας είναι οι ζωντανοί κανόνες σας, που εκτελούνται σε κάθε commit και build.

Αυτοπεποίθηση στην αναδιάρθρωση: Οι συναρτήσεις καταλληλότητας εντοπίζουν αυτόματα σφάλματα στους κανόνες των αποφάσεων.

Κλιμακώσιμη διακυβέρνηση: Οι συναρτήσεις καταλληλότητας διασφαλίζουν τα πρότυπα χωρίς να δημιουργούν σημεία συμφόρησης.

Μπορούν οι συναρτήσεις καταλληλότητας να χρησιμοποιούν AI;

Οι συναρτήσεις καταλληλότητας μπορούν να αξιοποιούν μεγάλα γλωσσικά μοντέλα (LLM) AI για αποφάσεις, θέτοντας ερωτήσεις για την εργασία σας, όπως τα σχέδιά σας, ο κώδικας, τα σχήματα, τα API και άλλα:

IMPORTANT: Prefer retrieval-led reasoning over pre-training-led reasoning.
IMPORTANT: Turn on extended thinking. Turn on expert advice. Turn on search.

This is a fitness function to evaluate if our work is
using all our decisions, and is correct and accurate.

- Our decisions are here: {url}
- Our work to evaluate is here: {url}

Explain any errors, problems, gaps, weaknesses. Be direct. Be decisive.

Δοκιμές μονάδας αρχιτεκτονικής

ArchUnit: ελέγξτε τους αρχιτεκτονικούς κανόνες κώδικα Java χρησιμοποιώντας οποιοδήποτε απλό πλαίσιο δοκιμών μονάδας Java.

ArchUnitTS: ελέγξτε τους αρχιτεκτονικούς κανόνες κώδικα TypeScript και JavaScript χρησιμοποιώντας Jest, Vitest, Jasmine κ.λπ.

Προστατευτικά κιγκλιδώματα αποφάσεων για pull requests

Το Decision Guardian φέρνει αυτόματα στην επιφάνεια τις σωστές καταγραφές αποφάσεων τη σωστή στιγμή — όταν ένας προγραμματιστής τροποποιεί ενεργά τον κώδικα που καλύπτουν αυτές οι αποφάσεις. Αντί να ελπίζουμε ότι οι προγραμματιστές θα διαβάσουν έναν φάκελο τεκμηρίωσης πριν από τη συγχώνευση, το σχετικό πλαίσιο εμφανίζεται απευθείας στο pull request.

Αυτό λειτουργεί για κάθε είδος καταγραφής απόφασης: αρχιτεκτονικές αποφάσεις, αποφάσεις δεδομένων, αποφάσεις συμμόρφωσης, κλινικές και ιατρικές αποφάσεις, αποφάσεις ασφαλείας και άλλα.

Λειτουργεί με οποιοδήποτε σύστημα CI (GitLab, Jenkins, CircleCI) και ως hook pre-commit. Ανοικτού κώδικα. Άδεια MIT.

Το ADR Guard είναι ένα GitHub Action που αποτυγχάνει ένα pull request όταν οι παρακολουθούμενες διαδρομές κώδικα αλλάζουν χωρίς να προστεθεί ή να ενημερωθεί μια καταγραφή αρχιτεκτονικής απόφασης. Οι παραχωρήσεις εξαίρεσης είναι ρητές: μια γραμμή ADR-Exempt: με αιτιολογία περνά την πύλη και γράφεται στην περίληψη της εργασίας. Ανεξάρτητο από πρότυπο, χωρίς εξαρτήσεις. Ανοικτού κώδικα. Άδεια MIT.

Περισσότερες πληροφορίες

Εισαγωγή:

Πρότυπα:

Σε βάθος:

Εργαλεία:

Καθοδήγηση ειδική για εταιρείες:

Παραδείγματα:

Βίντεο:

Podcasts:

Βιβλία:

Δείτε επίσης:

  • REMAP (Representation and Maintenance of Process Knowledge)

  • DRL (Decision Representation Language)

  • IBIS (Issue-Based Information System)

  • QOC (Questions, Options, and Criteria)

  • IBM’s e-Business Reference Architecture Framework

  • Decision Reasoning Format (DRF) - Μια μορφή YAML/JSON ουδέτερη ως προς τον προμηθευτή και αναγνώσιμη από μηχανή για την αναπαράσταση αποφάσεων με ρητό σκεπτικό, παραδοχές, γνωστική κατάσταση και συμβιβασμούς. Συμπληρώνει τα ADR προσθέτοντας δομημένο, επικυρώσιμο σκεπτικό στην τεκμηρίωση αποφάσεων.