Document-Driven Human-AI Collaboration: An Empirical Study of AI Agent Development Methodology

The Concept and Process of Documentation-First

Agent Configuration & Document Interaction

System Architecture

Deployment Plan

Phase 1: Project Scaffolding & Data Layer Setup (Day 1)

Phase 2: Global Layout & Core Homepage Sections (Day 2)

Phase 3: Motion Enhancement & VN Game-style UI System (Day 3)

Phase 4: Intro Prologue System Development (Day 4–Day 6)

Phase 5: Mobile Adaptation & Interaction Enhancement (Day 7–Day 10)

Phase 6: Code Cleanup & Document System Restructuring (Day 11–Day 12)

Phase 7: Data Layer Restructuring & Deployment Preparation (Day 13)

Challenge 1: Complex OpenCode Configuration

Challenge 2: Time Investment in Requirements Discussion & Documentation

Challenge 3: AI Agent Struggles to Proactively Identify Blind Spots

Challenge 4: Humans Struggle to Precisely Describe UI Feel

Challenge 5: Deviation Between Documentation and Implementation

Challenge 6: High Maintenance Cost of Document Synchronization

• AGENTS.md instruction stability is insufficient
• It would occupy context window space that may impact core tasks
• Automation might distract the Agent during critical feature development

Challenge 7: AI Agent Loses Focus in Long Sessions

Deliverables Overview

Features

Code & Architecture Quality

• Full TypeScript Strict: tsconfig.json enables strict + noUncheckedIndexedAccess + noImplicitReturns, all component Props wrapped with Readonly<{...}>
• Tailwind CSS v4 Design Tokens: @theme defines complete color system (primary/secondary/accent/dialog-blue, etc.), fonts, spacing, border radius, shadows
• Zod Data Validation: All JSON data files pass schema type checking, zero CMS/Database
• CI/CD: GitHub Actions runs lint → typecheck → build, Node.js 22.x
• Server/Client Component Boundary: Strict separation of server-side data reading and client-side animation interactions

Online Links

Advantages of the Documentation-First + Agent Approach

Natural Advantages of OpenCode CLI

• Multi-window Parallel Development: OpenCode CLI's lightweight architecture allows running multiple independent sessions simultaneously, each focusing on different feature modules (e.g., one window developing components, another synchronizing documents) without interference. This effectively reduces serial waiting time, but requires each window's tasks to have clear documentation constraints and quality acceptance standards — without a documentation baseline, multi-window parallelism may lead to code style fragmentation or architectural inconsistency.

• Local Deployment for Data Security: OpenCode natively supports connecting to local Ollama models, providing an ideal solution for projects involving confidential information or undisclosed business logic. All code and documents needed for Agent development can run entirely locally without uploading to any third-party API service.

Inherent Limitations

Workflow & Role Transformation

Team Scenario Extrapolation

HR/Management Perspective

• Agent configuration and tuning have a learning curve; results depend on the user's proficiency with the tool
• There is a direct trade-off between documentation granularity and output stability — the more detailed the documentation (greater upfront investment), the more stable the Agent output; choosing between fast-start-with-extensive-optimization versus slower-start-with-minor-optimization depends on the project's different requirements for delivery speed and quality

Open Source & Commercial Boundaries

Documentation Density Over Iterative Fixing

Upgraded Understanding of Agent Development Capabilities

Practical Advice on Tool Selection

Core Findings

Applicable Scenarios

• Developers with relatively clear requirements expectations, prioritizing delivery quality over rapid prototype validation
• Projects of moderate scale (personal projects or small teams), where documentation maintenance costs are manageable
• Developers with some software engineering knowledge who can write structured design documents

Future Directions

Appendix A: Complete Document System Inventory

Appendix B: OpenCode Agent Configuration Highlights

{
  "instructions": [".opencode/skills/frontend-design/SKILL.md"],
  "permission": {
    "external_directory": {
      "E:/Xeno/Obsidian/2DportfolioDocuments/**": "allow"
    },
    "edit": {
      "E:/Xeno/Obsidian/2DportfolioDocuments/**": "ask"
    }
  }
}

• `external_directory`: Grants the Agent permission to read the Obsidian document library, enabling direct access to all 20+ design documents during development sessions
• `edit.ask`: Modifications to Obsidian documents require manual confirmation, preventing the Agent from changing design documents without review
• `instructions`: Loads the frontend-design skill, injecting frontend design decision guidance into the Agent
• AGENTS.md: Injects project context at the project root, covering framework version, architecture conventions, component specifications, routing rules, etc.

Appendix C: Dependency & Version Details

Appendix D: CI/CD Pipeline Configuration

name: CI
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  ci:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      - run: pnpm run lint
      - run: pnpm run typecheck
      - run: pnpm run build

Appendix E: Development Environment Specifications

References