103 lines
4.0 KiB
Markdown
103 lines
4.0 KiB
Markdown
Architecture Manual
|
|
===
|
|
|
|
You are documenting the architecture and design decisions of a software project. This is a TEMPLATE containing placeholders in square brackets (e.g. `[STACK_NAME]`, `[PATTERN_NAME]`, etc.)
|
|
|
|
## Mission
|
|
|
|
- Ensure `ARCHITECTURE.md` provides a updated and comprehensive overview of the project's architecture.
|
|
- Record significant architecture decisions using Architecture Decision Records (ADRs).
|
|
- Maintain clarity and consistency architecture choices and patterns.
|
|
|
|
## Directory Structure
|
|
|
|
The architecture documentation is organized as follows:
|
|
|
|
```
|
|
|- docs/
|
|
|- ADRs/ # Architecture Decision Records
|
|
|- [date]-[decision-title].md # Individual ADR files
|
|
|- ARCHITECTURE.md # Main architecture document
|
|
```
|
|
|
|
## Steps (Strict Order)
|
|
|
|
### 1. Prepare Architecture Document
|
|
|
|
Use `cp` command to copy the architecture template from `./templates/architecture.md` to `docs/ARCHITECTURE.md` if it does not already exist.
|
|
|
|
### 2. Copy Decision Record Template
|
|
|
|
Use `cp` command to copy the ADR template from `./templates/adr.md` to `docs/ADRs/[date]-[decision-title].md` for each significant architecture decision that needs to be documented.
|
|
|
|
**NOTE**: The initial record should document technology stack choices made for the project and structure of the codebase which is minimal requirement for `ARCHITECTURE.md`.
|
|
|
|
### 3. Read Existing Architecture Document
|
|
|
|
Identify every placeholder token of the form `[ALL_CAPS_IDENTIFIER]` in the template. Create a series of questions to ask the user for each decision is made.
|
|
|
|
- `DATE`: Use today's date in `YYYY-MM-DD` format.
|
|
- `DECISION_TITLE`: A concise title summarizing the decision (e.g., `use-redis-caching`).
|
|
|
|
### 4. Gather Required Information
|
|
|
|
Ask user for each placeholder to clarify the architecture decisions and patterns used in the project. Ask questions one by one and infer next question based on user's answers.
|
|
|
|
NEVER make assumptions about architecture choices without explicit answers from the user.
|
|
|
|
Example questions to ask the user:
|
|
|
|
```
|
|
Q: What programming languages are used in the project?
|
|
- A: [User's Specified Languages]
|
|
|
|
Q: Will use any specific frameworks or libraries?
|
|
- A: Ruby on Rails # infer from user's answer
|
|
- B: Other: [User's Specified Frameworks]
|
|
|
|
Q: What database systems are utilized?
|
|
# ...
|
|
```
|
|
|
|
### 5. Draft Decision Record
|
|
|
|
Update decision record content one by one according to the user's answers and inferred information.
|
|
|
|
- Replace each placeholder in the ADR template with the relevant information.
|
|
- Preserve the heading hierarchy and formatting of the template.
|
|
- Ensure clarity and completeness of each section in the ADR.
|
|
|
|
### 6. Validate Decision Record
|
|
|
|
- Ensure no placeholder tokens remain in the ADR.
|
|
- Check for consistency and accuracy of the documented decisions.
|
|
- Confirm with the user that the ADR accurately reflects their architecture choices.
|
|
- `DATE`: Use today's date in `YYYY-MM-DD` format.
|
|
|
|
### 7. Finalize Decision Record
|
|
|
|
Save the completed ADR in the `docs/ADRs/` directory with the appropriate filename.
|
|
|
|
### 8. Synchronize Architecture Document
|
|
|
|
Update `docs/ARCHITECTURE.md` to reflect the newly created ADRs and any changes in architecture decisions.
|
|
|
|
- The architecture document is aggregated state of all ADRs, ensure consistency between them.
|
|
- The newer ADRs is higher priority than older ones.
|
|
- `ARCHITECTURE.md` should provide a high-level overview of the architecture, do not explain every detail in ADRs again.
|
|
- Ensure heading hierarchy and formatting is preserved and must same as the template.
|
|
|
|
### 9. Summarize Changes
|
|
|
|
- Provide a summary of the changes made to the architecture documentation.
|
|
- Highlight any significant decisions or patterns that were added or modified.
|
|
- The path of newly created ADR file.
|
|
|
|
## Constraints
|
|
|
|
- Create only one ADR per significant architecture decision.
|
|
- Working on one ADR at a time, do not mix multiple decisions in a single record.
|
|
- Always update `ARCHITECTURE.md` after finalizing each ADR.
|
|
- Do not make any decisions without explicit confirmation from the user.
|
|
|