生成AIを活用したレガシーマイグレーション案件における現行システム理解のTips

はじめに

こんにちは或いはこんばんは。Ryuzakiです。

最近仕事でレガシーマイグレーション案件に関わる経験がありました。全く知らないフレームワーク、かつ、対象コードが多かったこともあり、どこから手を付ければいいかわからないような状況だったのですが、生成AIを上手く活用することで短時間で現行システムを理解することができました。

レガシーシステムの解析って、ドキュメントが古い（あるいは存在しない）、担当者が既にいない、技術スタックが古すぎて情報が少ない、といった課題がつきものですよね。こういった状況で生成AIを効果的に活用できれば、システム理解の効率を大幅に向上させることができます。

今回はこの経験で得られたTipsを共有させていただきます。

本記事のポイント

• 大規模なレガシーシステムを短時間で理解する手法
• 生成AIを活用した効率的なコード解析方法
• 実用的な仕様書作成のプロセス

現行システムを理解する手順

例があった方がわかりやすいと思うため、今回は複雑な業務システムのサンプルとしてGitHubで公開されているgreat-big-example-applicationを例として説明を行います。

https://github.com/dancancro/great-big-example-application/tree/master

今回の検証はClaude Desktop + Claude Sonnet 4で実施しています。
また、大規模なシステムの場合はトークン数がかさみがちなため、少しでもトークン数を削減するためにすべて英語で進めています。

1. 現行システムのディレクトリ構成を取得

まず最初に、次のステップで生成AIに「どのファイルを確認すべきか」ということを効果的に質問をするために、現行システムのディレクトリ構成をファイルレベルまでツリー形式で出力します。

# treeコマンドを利用した場合のコマンド例
tree -a . -o "project-structure.txt"

このコマンドを実行すると、以下のような出力が得られます。

ディレクトリ構成の出力例（抜粋）

great-big-example-application-master
├── LICENSE
├── NOTICES.md
├── PhantomJS_2.1.1_(Mac_OS_X_0.0.0)
│   └── target
│       └── test-results
│           └── karma
│               └── TESTS-results.xml
├── Procfile
├── README.md
├── docs
│   ├── FILE_STRUCTURE.md
│   ├── config.json
│   ├── contents
│   │   ├── articles
│   │   │   ├── 001-getting-started
│   │   │   │   └── index.md
│   │   │   ├── 002-installation-guidelines
│   │   │   │   └── index.md
│   │   │   ├── 011-changing-color-scheme
│   │   │   │   ├── index.md
│   │   │   │   └── new-color-scheme.png
│   │   │   ├── 012-project-structure
│   │   │   │   └── index.md
│   │   │   ├── 013-create-new-page
│   │   │   │   └── index.md
│   │   │   ├── 014-switch-to-blur-theme
│   │   │   │   └── index.md
│   │   │   ├── 015-sidebar
│   │   │   │   └── index.md
│   │   │   ├── 016-spinner
│   │   │   │   └── index.md
│   │   │   ├── 101-loading-middleware
│   │   │   └── 102-troubleshooting.md
│   │   ├── css
│   │   │   └── main.scss
│   │   ├── images
│   │   │   ├── favicon.png
│   │   │   ├── logo.png
│   │   │   ├── sky-preview.png
│   │   │   ├── why-design.svg
│   │   │   ├── why-practices.svg
│   │   │   └── why-structure.svg
│   │   └── index.json
...

2. システムを理解するのに確認すべきファイルを生成AIに質問

1.で取得したディレクトリ構成の情報とともに、以下のようなプロンプトを実行します。

確認すべきファイルを質問するプロンプトの例

Which files should I read to create a specification document of the current system? Use code blocks to list the files I should check. You can use wildcard syntax (*) if necessary.

日本語訳したプロンプト

現行システムの仕様書を作成するのにどのファイルを参照すればいいかを教えて下さい。なお、参照すべきファイルの一覧はコードブロック形式で出力してください。また、必要ならワイルドカード（*）シンタックスを用いてください。

生成AIからの回答例

Looking at this comprehensive directory structure, I can see this is a large full-stack application with Java/Kotlin backend and Angular frontend. To create a thorough specification document, I should examine files in this order of priority:

1. Project Overview & Documentation

README.md
LICENSE
docs/FILE_STRUCTURE.md
docs/contents/articles/*/index.md
package.json
pom.xml

2. Backend API & Data Models

src/main/java/org/exampleapps/greatbig/domain/*.java
src/main/java/org/exampleapps/greatbig/web/rest/*Resource.java
src/main/java/org/exampleapps/greatbig/service/*.java
src/main/java/org/exampleapps/greatbig/config/*.java
src/main/kotlin/org/exampleapps/greatbig/domain/*.kt
src/main/kotlin/org/exampleapps/greatbig/web/rest/*Handler.kt

3. Database Schema & Configuration

src/main/resources/config/liquibase/changelog/*.xml
src/main/resources/config/application*.yml
schema.jdl

4. Frontend Features & Architecture

src/main/webapp/app/features/*/README.md
src/main/webapp/app/app.module.ts
src/main/webapp/app/app.routing.ts
src/main/webapp/app/core/**/*.ts
src/main/webapp/app/features/*/*.module.ts
src/main/webapp/app/features/*/*.routing.ts

5. Key Entity Management

src/main/webapp/app/entities/*/index.ts
src/main/webapp/app/entities/*/*.model.ts
src/main/webapp/app/entities/*/*.service.ts

6. Core Services & State Management

src/main/webapp/app/core/store/**/*.ts
src/main/webapp/app/core/services/*.ts
src/main/webapp/app/shared/**/*.service.ts

7. Configuration & Deployment

Procfile
firebase.json
Dockerfile
src/main/docker/*.yml
webpack/*.js

Should I start by reading these files systematically to build the specification document?

生成AIは優先度順にファイルをリストアップしてくれるため、限られた時間の中でも効率的にシステムを理解できます。

3. 対象ソースコードを1つのMarkdownファイルにまとめる

次に、優先度が最も高かったファイルのグループを1つのMarkdownファイルにまとめます。今回はcode2promptを用いてソースコードのMarkdown化を実施しました。

https://github.com/mufeedvh/code2prompt/tree/main

code2promptについて

code2promptは、ソースコードを生成AI向けのMarkdown形式に変換する便利なツールです。大規模なプロジェクトから必要なファイルだけを抽出し、適切にフォーマットしてくれます。

主な特徴：

• ファイルパスとコンテンツを組み合わせたMarkdown出力
• 包含・除外パターンの柔軟な指定
• トークン数の概算表示機能

詳細な使い方については、以下の公式ドキュメントを参照してください。

# プロジェクトルートで実行している前提
# --includeオプションを用いることで特定のファイルのみを含めることが可能
# -Oオプションを用いてファイルとして書き出すのがオススメ
code2prompt . --include="path/from/root/target-file-1.java,path/from/root/target-file-2.java" -O "/path/to/output/output.md"

# 具体的なコマンドの例
code2prompt . --include="README.md,LICENSE,docs/FILE_STRUCTURE.md,docs/contents/articles/*/index.md,package.json,pom.xml" -O "project-overview.md"

トークン数の調整について

Markdownファイルのサイズが大きすぎる（最大5万トークン、感覚的には2~3万トークン程度がベスト）場合は、対象とするファイルを絞って、再度Markdown化を行なってください。サイズが大きすぎるとハルシネーションを起こしたり、十分な情報を抽出できなかったりします。

4. ソースコードをまとめたMarkdownファイルをインプットとしてシステム仕様書を作成

2.でディレクトリ構成を解析させたのと同じセッションで、以下のようなプロンプトを用いてシステム仕様書を作成します。

システム仕様書作成用プロンプトの例

I've uploaded the code of the files specified in group1. Please create a comprehensive specification document using this information.

日本語訳したプロンプト

グループ1で示されたファイルのコードをアップロードしました。この情報を用いて包括的な仕様書を作成してください。

生成された仕様書の例

Great Big Example Application - System Specification

Table of Contents

1. Project Overview
2. System Architecture
3. Technology Stack
4. Project Structure
5. Core Features
6. Frontend Architecture
7. Backend Architecture
8. Database Design
9. Security Implementation
10. Build and Deployment
11. Testing Strategy
12. Development Setup
13. API Documentation
14. Configuration Management

Project Overview

Purpose

The Great Big Example Application is a comprehensive, production-ready web application that serves as a reference implementation for modern full-stack development practices. It combines multiple small open-source demos into one cohesive application to demonstrate how enterprise-level applications are actually built.

Key Objectives

• Provide a single, comprehensive example of production-grade code
• Demonstrate integration of multiple technologies and patterns
• Serve as a learning resource for Angular and Spring Boot development
• Showcase best practices for state management, routing, and component architecture
• Eliminate the need to piece together knowledge from multiple, inconsistent tutorials

Target Audience

• Developers learning modern web application development
• Teams looking for architectural guidance for enterprise applications
• Engineers seeking examples of real-world implementation patterns

System Architecture

High-Level Architecture

The application follows a modern three-tier architecture:

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Presentation  │    │   Application   │    │      Data       │
│     Layer       │    │     Layer       │    │     Layer       │
│                 │    │                 │    │                 │
│   Angular SPA   │◄──►│  Spring Boot    │◄──►│   PostgreSQL    │
│   TypeScript    │    │   Java/Kotlin   │    │   H2 Database   │
│   Bootstrap     │    │   REST APIs     │    │   MongoDB       │
└─────────────────┘    └─────────────────┘    └─────────────────┘

Architecture Principles

• Separation of Concerns: Clear separation between frontend and backend logic
• Modular Design: Feature-based module organization
• Scalability: Horizontal scaling capabilities through microservice-ready patterns
• Maintainability: Clean code practices and comprehensive documentation
• Testability: Extensive test coverage at all levels

Technology Stack

Frontend Technologies

• Framework: Angular 4.4.3
• Language: TypeScript, ES6/ES2015
• State Management: ngrx 4.0 (Redux pattern)
• UI Framework: Bootstrap 4.0.0-beta, Angular Material 2.0.0-beta.7
• Build Tool: Webpack 3.6.0, Angular CLI 1.3.0
• Package Manager: Yarn, NPM
• CSS Preprocessor: SASS/SCSS
• Animation: CSS3 Animations, Angular Animations

Backend Technologies

• Framework: Spring Boot 1.5.4
• Languages: Java 8, Kotlin 1.1.4
• Database: PostgreSQL, H2 (development), MongoDB
• ORM: Hibernate 5.2.8, Spring Data JPA
• Security: Spring Security, JWT (JSON Web Tokens)
• API Documentation: Swagger/OpenAPI
• Caching: Ehcache, Spring Cache
• Search: Elasticsearch
• Message Queue: WebSocket, STOMP

DevOps & Tools

• Build Tools: Maven 3.0+, Webpack
• Testing: Karma, Jasmine, Protractor, JUnit, Mockito, Gatling
• Code Quality: TSLint, ESLint, SonarQube
• Containerization: Docker
• CI/CD: Support for various CI platforms
• Monitoring: Micrometer, Prometheus, Grafana

Third-Party Libraries

• Charts: Chart.js, AmCharts, Chartist
• Maps: Leaflet, Google Maps
• Date/Time: Moment.js
• Utilities: Lodash, RxJS
• File Upload: ngx-uploader
• Notifications: angular2-notifications

Project Structure

Root Level Structure

great-big-example-application/
├── docs/                    # Documentation and guides
├── e2e/                     # End-to-end tests
├── src/
│   ├── main/
│   │   ├── java/            # Java backend code
│   │   ├── kotlin/          # Kotlin backend code
│   │   ├── resources/       # Configuration and static resources
│   │   └── webapp/          # Frontend application
│   └── test/                # Test code (Java, Kotlin, JavaScript)
├── webpack/                 # Webpack configuration files
├── package.json             # Frontend dependencies
├── pom.xml                  # Backend dependencies (Maven)
└── yarn.lock               # Yarn lock file

Frontend Structure (src/main/webapp/app/)

app/
├── account/                 # User account management
├── admin/                   # Administrative features
├── core/                    # Core services and state management
│   ├── api/                 # API services
│   ├── commands/            # Command pattern implementation
│   ├── interceptor/         # HTTP interceptors
│   ├── services/            # Core business services
│   └── store/               # ngrx state management
├── entities/                # CRUD entity management
├── features/                # Feature modules
│   ├── about/
│   ├── bernie/              # Political claims and rebuttals
│   ├── blog/                # Blog/article system
│   ├── books/               # Book collection management
│   ├── chat/                # Real-time chat
│   ├── contacts/            # Contact management
│   ├── counter/             # Simple counter demo
│   ├── dashboard/           # Analytics dashboard
│   ├── game/                # Typing speed game
│   ├── heroes/              # Tour of Heroes demo
│   ├── meals/               # Recipe/meal planning
│   ├── messages/            # Message system
│   ├── notes/               # Drag-and-drop notes
│   ├── talks/               # Tech talks management
│   └── wiki/                # Wikipedia integration
├── layouts/                 # Layout components
├── shared/                  # Shared components and utilities
└── vendor.ts               # Third-party library imports

Backend Structure (src/main/java/)

org/exampleapps/greatbig/
├── config/                  # Configuration classes
├── domain/                  # JPA entities
├── repository/              # Data access layer
├── security/                # Security configuration
├── service/                 # Business logic services
└── web/rest/               # REST API controllers

Core Features

1. Authentication & Authorization

• JWT-based Authentication: Stateless token-based security
• Social Login: Integration with Google, Facebook, Twitter
• Role-based Access Control: Admin and user roles
• Password Management: Reset, change, strength validation

2. User Management

• User Registration: Email verification workflow
• Profile Management: User settings and preferences
• Admin Console: User administration interface
• Session Management: Active session tracking

3. Content Management

• Blog System: Article creation, editing, commenting
• File Upload: Multi-file upload with progress tracking
• Rich Text Editing: WYSIWYG editor integration
• Media Management: Image and document handling

4. Real-time Features

• Chat System: WebSocket-based messaging
• Live Updates: Real-time data synchronization
• Notifications: Toast and banner notifications
• Activity Tracking: User activity monitoring

5. Data Visualization

• Dashboard: Interactive charts and metrics
• Multiple Chart Types: Line, pie, bar, area charts
• Real-time Data: Live updating visualizations
• Export Functionality: Chart and data export

6. Advanced UI Components

• Drag & Drop: Sortable lists and components
• Data Tables: Sortable, filterable, paginated tables
• Calendar: Event scheduling and management
• Maps: Interactive mapping features
• Modal Dialogs: Popup interfaces

7. Search & Filtering

• Full-text Search: Elasticsearch integration
• Advanced Filtering: Multi-criteria filtering
• Autocomplete: Type-ahead search suggestions
• Search History: Recent search tracking

8. Internationalization

• Multi-language Support: English, German, Spanish, French
• Dynamic Language Switching: Runtime language changes
• Localized Content: Date, number, currency formatting
• RTL Support: Right-to-left language support

Frontend Architecture

State Management (ngrx)

The application uses ngrx for predictable state management following Redux patterns:

// Store Structure
interface AppState {
  account: AccountState;
  articles: ArticleState;
  books: BookState;
  claims: ClaimState;
  contacts: ContactState;
  heroes: HeroState;
  layout: LayoutState;
  messages: MessageState;
  notes: NoteState;
  session: SessionState;
  talks: TalkState;
}

Key ngrx Features

• Actions: Type-safe action creators
• Reducers: Pure functions for state updates
• Effects: Side effect management with RxJS
• Selectors: Memoized state selection
• Store DevTools: Development debugging support

Component Architecture

• Smart/Container Components: Connected to store, handle business logic
• Dumb/Presentational Components: Pure components, receive data via inputs
• Service Layer: Business logic abstraction
• Guard Services: Route protection and data resolution

Routing Strategy

• Feature-based Routing: Lazy-loaded feature modules
• Route Guards: Authentication and authorization checks
• Route Resolvers: Pre-load data before navigation
• Child Routes: Nested routing for complex features

Styling Architecture

• SCSS/SASS: Advanced CSS preprocessing
• Theme System: Configurable color schemes
• Component Styles: Encapsulated component styling
• Responsive Design: Mobile-first responsive layouts
• CSS Modules: Modular CSS organization

Backend Architecture

Spring Boot Configuration

The backend follows Spring Boot conventions with custom configurations:

Core Configurations

• SecurityConfiguration: JWT and OAuth setup
• DatabaseConfiguration: Multi-database support
• WebsocketConfiguration: Real-time communication
• CacheConfiguration: Application-level caching
• AsyncConfiguration: Asynchronous processing

REST API Design

• RESTful Principles: Standard HTTP methods and status codes
• Resource-based URLs: Clear, predictable endpoint structure
• HATEOAS: Hypermedia-driven API design
• Versioning: API version management
• Content Negotiation: JSON/XML response formats

Security Implementation

• JWT Tokens: Stateless authentication
• CORS Configuration: Cross-origin request handling
• CSRF Protection: Cross-site request forgery prevention
• Method-level Security: Fine-grained access control
• Audit Logging: Security event tracking

Data Access Layer

• Spring Data JPA: Repository pattern implementation
• Custom Repositories: Complex query implementations
• Transaction Management: Declarative transaction handling
• Database Migration: Liquibase change management
• Connection Pooling: HikariCP for optimal performance

Database Design

Primary Database (PostgreSQL)

The application uses PostgreSQL as the primary database with the following key entities:

Core Entities

• User: User account information
• Authority: Role-based permissions
• Article: Blog posts and content
• Comment: User comments on articles
• Tag: Content categorization
• Note: User notes with positioning
• Message: Chat messages
• Hero: Tour of Heroes entities
• Contact: Contact information
• Talk: Technical presentation data

Relationship Patterns

• Many-to-Many: User-Article favorites, Article-Tag associations
• One-to-Many: User-Comment, Article-Comment relationships
• Hierarchical: Nested comment structures
• Audit Fields: Created/modified timestamps and users

Search Database (Elasticsearch)

• Full-text Search: Optimized search capabilities
• Faceted Search: Multi-dimensional filtering
• Autocomplete: Type-ahead suggestions
• Analytics: Search metrics and reporting

Caching Strategy

• Application Cache: Ehcache for frequently accessed data
• HTTP Cache: Browser caching headers
• Database Cache: Query result caching
• Session Cache: User session data

Security Implementation

Authentication Flow

1. User Login: Credentials validation
2. JWT Generation: Token creation with user claims
3. Token Storage: Secure client-side storage
4. Request Authentication: Token validation on each request
5. Token Refresh: Automatic token renewal

Authorization Levels

• Public: Unrestricted access
• User: Authenticated user access
• Admin: Administrative privileges
• System: Internal system operations

Security Features

• Password Encryption: BCrypt hashing
• Account Lockout: Brute force protection
• Session Management: Concurrent session control
• Audit Trail: Security event logging
• Data Validation: Input sanitization and validation

Social Authentication

• Google OAuth: Google account integration
• Facebook Login: Facebook social login
• Twitter Auth: Twitter account linking
• Account Linking: Multiple provider association

Build and Deployment

Development Build

# Backend development server
./mvnw spring-boot:run

# Frontend development server
yarn start

Production Build

# Full production build
./mvnw package -Pprod

# Frontend only
yarn run webpack:prod

Docker Deployment

# Multi-stage Docker build
FROM openjdk:8-jdk-alpine
COPY target/*.war app.war
ENTRYPOINT ["java","-jar","/app.war"]

Heroku Deployment

• Procfile: Heroku process definition
• Environment Variables: Configuration management
• Database: PostgreSQL addon
• Buildpacks: Multi-buildpack setup

Build Profiles

• dev: Development with hot reload
• prod: Production optimized build
• webpack: Frontend asset compilation
• docker: Containerized deployment

Testing Strategy

Frontend Testing

• Unit Tests: Karma + Jasmine
• Component Tests: Angular Testing Utilities
• Integration Tests: HTTP client mocking
• E2E Tests: Protractor + WebDriver

Backend Testing

• Unit Tests: JUnit + Mockito
• Integration Tests: Spring Boot Test
• Repository Tests: @DataJpaTest
• Web Layer Tests: @WebMvcTest

Performance Testing

• Load Testing: Gatling scenarios
• Stress Testing: High-concurrency tests
• Performance Monitoring: Metrics collection
• Profiling: Memory and CPU analysis

Test Coverage

• Code Coverage: Jacoco reporting
• Coverage Thresholds: Minimum coverage requirements
• Continuous Testing: Automated test execution
• Test Reporting: Detailed test results

Development Setup

Prerequisites

• Node.js: 6.11.0+ (LTS version)
• Yarn: Package manager
• Java: JDK 8+
• Maven: 3.0+
• PostgreSQL: 9.4+ (production)

Installation Steps

1. Clone Repository:

   git clone https://github.com/dancancro/great-big-example-application.git
   cd great-big-example-application
   

2. Install Dependencies:

   yarn install
   ./mvnw install
   

3. Database Setup:

   # Create PostgreSQL database
   createdb GreatBigExampleApplication
   

4. Run Application:

   # Terminal 1: Backend
   ./mvnw spring-boot:run
   
   # Terminal 2: Frontend
   yarn start
   

Development Tools

• IDE Configuration: IntelliJ IDEA, VS Code setup
• Browser DevTools: Redux DevTools extension
• Database Tools: pgAdmin, H2 Console
• API Testing: Swagger UI, Postman

Code Quality Tools

• Linting: TSLint, ESLint configuration
• Formatting: Prettier, EditorConfig
• Git Hooks: Pre-commit quality checks
• Static Analysis: SonarQube integration

API Documentation

Swagger/OpenAPI Integration

• API Explorer: Interactive API documentation
• Schema Generation: Automatic API schema
• Request Testing: Built-in API testing
• Code Generation: Client SDK generation

API Endpoints Overview

Authentication:
POST /api/authenticate           # User login
POST /api/account/reset-password # Password reset

User Management:
GET  /api/account               # Current user profile
POST /api/register              # User registration
PUT  /api/account               # Update profile

Content Management:
GET    /api/articles            # List articles
POST   /api/articles            # Create article
GET    /api/articles/{id}       # Get article
PUT    /api/articles/{id}       # Update article
DELETE /api/articles/{id}       # Delete article

Real-time:
/websocket/chat                 # WebSocket chat endpoint

API Design Standards

• RESTful URLs: Resource-based naming
• HTTP Status Codes: Proper status usage
• Error Handling: Consistent error responses
• Pagination: Standardized pagination
• Filtering: Query parameter conventions

Configuration Management

Application Profiles

• dev: Development environment settings
• prod: Production environment configuration
• test: Testing environment setup
• heroku: Heroku-specific configuration

Configuration Files

src/main/resources/config/
├── application.yml              # Base configuration
├── application-dev.yml          # Development settings
├── application-prod.yml         # Production settings
├── application-heroku.yml       # Heroku settings
└── liquibase/                   # Database migrations

Environment Variables

• Database Configuration: Connection strings, credentials
• External Services: API keys, service URLs
• Security Settings: JWT secrets, OAuth keys
• Feature Flags: Runtime feature toggles

External Service Configuration

• Social Login: OAuth provider settings
• Email Service: SMTP configuration
• File Storage: Cloud storage settings
• Monitoring: Metrics and logging configuration

---

Conclusion

The Great Big Example Application represents a comprehensive, production-ready implementation that demonstrates modern full-stack development practices. It serves as both a learning resource and a foundation for building enterprise-level web applications.

Key Takeaways

• Real-world Architecture: Production-grade patterns and practices
• Technology Integration: Seamless integration of multiple technologies
• Scalable Design: Architecture that supports growth and evolution
• Developer Experience: Comprehensive tooling and documentation
• Quality Assurance: Extensive testing and quality measures

This specification provides the foundation for understanding, maintaining, and extending the Great Big Example Application while serving as a reference for similar projects.

5. システム仕様書を肉付け

基本的な仕様書ができたら、他の箇所のソースコードも同様にMarkdown化し、段階的に仕様書を肉付けしていきます。

システム仕様書肉付け用プロンプトの例

## Task Instructions

You are tasked with analyzing uploaded documents and updating a specification document. Follow these steps:

1. **Read and understand the specification document** that the user has uploaded
2. **Analyze the Markdown file containing source code** that the user has uploaded
3. **Identify new information** from the source code analysis that was not mentioned in the original specification
4. **Output an updated specification document** that includes:
   - All original specification content (unchanged)
   - **Only** newly discovered information from the source code analysis
   - Do not modify or edit existing specification content

## Output Requirements

- **Do not modify** the original specification content
- **Only add** new information discovered from source code analysis
- Clearly mark newly added content as additions
- Maintain the original structure and format of the specification document

このプロセスにより、段階的に詳細で正確な仕様書を構築していくことができます。

肉付け作業のポイント

• 各Markdownファイルごとに新しいセッションで肉付け作業を行う
• ソースコードから新たに判明した情報のみを記載する（無関係の箇所には編集を加えない）ことをプロンプトに明記
• 可能ならFilesystem MCPのedit_fileツールのように、diff形式で追記を行うツールを利用

仕様書の管理について

仕様書自体が大きくなったら（2~3万トークン超）、以下のようなプロンプトを用いて、適宜圧縮や分割を行いましょう。

仕様書圧縮用プロンプトの例

Could you revise the specification document that I uploaded so it is more concise and has just enough information of the whole system?

仕様書分割用プロンプトの例（圧縮用プロンプト後に実施）

Could you also create a document that contains all the very specific (detailed) specifications? Create separate documents for each information. Only use information which was written in the original specification document.

おわりに

今回は生成AIを活用したレガシーシステムの理解手法について共有させていただきました。

この手法の最大のメリットは、従来であれば数週間から数ヶ月かかっていたシステム理解を、数日から1週間程度に短縮できることです。特に、ドキュメントが不十分なレガシーシステムや、技術スタックが古くて情報が少ないシステムの場合、生成AIの力を借りることで効率的にシステム全体を把握できます。

また、作成した仕様書は新しいメンバーのオンボーディングや、将来のマイグレーション計画策定にも活用できるため、一度作成しておくと継続的な価値を提供してくれます。

同様の課題に直面している方の参考になれば幸いです。ここまでお読みいただき、ありがとうございました。