From 6b4452736d4ce97b4496967dab5a4dd619a049c9 Mon Sep 17 00:00:00 2001 From: kric_jspark Date: Fri, 7 Aug 2026 14:06:27 +0900 Subject: [PATCH] docs: add AI agent harness configuration --- .agent/profile.yml | 26 +++++ .agent/project.md | 32 ++++++ .gitattributes | 4 + AGENTS.md | 275 +++++++++++++++++++++++++++++++++++++++++++++ CLAUDE.md | 1 + 5 files changed, 338 insertions(+) create mode 100644 .agent/profile.yml create mode 100644 .agent/project.md create mode 100644 .gitattributes create mode 100644 AGENTS.md create mode 100644 CLAUDE.md diff --git a/.agent/profile.yml b/.agent/profile.yml new file mode 100644 index 0000000..8e63ab6 --- /dev/null +++ b/.agent/profile.yml @@ -0,0 +1,26 @@ +schema_version: 1 + +project: + id: asp-kon-kiwi + name: KON-KIWI + type: internal-service + layer: fullstack + legacy: true + +stack: + - classic-asp + +databases: + - id: kon-kiwi + engine: mssql + role: primary-application-data + access: read-write + +migration: + status: planned + target_stack: + - typescript + - react + - nextjs + - java-springboot + strategy: staged diff --git a/.agent/project.md b/.agent/project.md new file mode 100644 index 0000000..a05c42b --- /dev/null +++ b/.agent/project.md @@ -0,0 +1,32 @@ +## KON-KIWI Repository Rules + +### Repository Role and Twin-Project Relationship + +- This is a legacy Classic ASP application maintained alongside `KON`; the two repositories are near twins whose main differences are presentation and styling. +- Preserve current routes, includes, sessions, authentication, authorization, form fields, redirects, uploads, downloads, and MSSQL behavior while the application remains in service. +- Before changing shared-looking behavior, compare the corresponding KON implementation and determine whether the change belongs in both repositories or only this one. +- Do not copy a change across the pair blindly. Preserve intentional branding, layout, CSS, asset, configuration, customer, and deployment differences. +- Keep maintenance and small approved feature work narrowly scoped. Do not modernize unrelated business areas or shared include trees as a side effect. + +### Encoding and File Safety + +- Treat Classic ASP, include, script, and configuration files as potentially CP949/EUC-KR with CRLF. Verify each touched file's encoding, BOM state, line endings, response code page, and charset behavior before and after editing. +- Never run a repository-wide UTF-8 conversion, formatter, or line-ending normalization. Inspect byte-level diffs and Korean comments, messages, labels, and data after every approved text change. +- Treat existing connection settings and operational configuration as sensitive legacy material. Do not echo their values into chat, logs, fixtures, generated documentation, or completion reports, and do not alter them without explicit task scope. + +### Runtime and Repository Data + +- `Project`, `log`, `ProjectUpload`, `uploadFile`, `WebProject`, `_ServerLog`, and `Files` retain only `.gitkeep`; do not add runtime contents from these directories to Git. +- `store` is intentionally versioned. Preserve its tracked contents and do not add it to ignore rules or remove it as cleanup without explicit approval. +- Do not modify uploaded files, generated projects, logs, or runtime artifacts during analysis or validation. + +### Data and Migration Direction + +- Trace include chains and shared DB helpers before changing SQL, authentication, authorization, sessions, uploads, or file handling. +- Parameterize new or changed values while preserving ADO parameter order, types, result shapes, transactions, null behavior, and ordering. +- The long-term direction is staged migration to a Spring Boot backend and Next.js/TypeScript frontend. For now, record relevant migration observations briefly and prioritize safe legacy maintenance. + +### Harness and Verification + +- `AGENTS.md` and `CLAUDE.md` are generated. Edit `.agent/profile.yml` or `.agent/project.md`, then recompose instead of editing generated files. +- Do not start IIS, connect to a real database, send external requests, or mutate production-like data during validation without separate approval. diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..ee26f61 --- /dev/null +++ b/.gitattributes @@ -0,0 +1,4 @@ +/.gitattributes text eol=lf +/.agent/** text eol=lf +/AGENTS.md text eol=lf +/CLAUDE.md text eol=lf diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..155a29f --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,275 @@ + + +# KRI Development Base Instructions + +This document defines the shared working rules for KRI development repositories. +Keep project-specific facts and commands in the project profile and project rules. + +## Instruction Resolution + +Apply repository instructions in this order: + +1. Base rules +2. Project-type rules +3. Technology-stack rules +4. Shared consumer contracts +5. Project-specific rules +6. The explicitly approved task scope + +Later and more specific instructions may override earlier general instructions only within their stated scope. + +- Apply a shared consumer contract only when `.agent/profile.yml` declares it. +- Do not silently resolve a material instruction conflict. Report the conflicting rules and request a decision before changing files. +- Rules involving destructive actions, credentials, external systems, production, deployment, databases, or Git publication require explicit authorization even when a later rule is less restrictive. + +## Communication + +- Respond to the user in Korean unless the user requests another language. +- Keep code identifiers, commands, paths, protocol names, and external API terms in their original form. +- Follow the repository's existing language conventions for code comments and user-facing messages. +- Lead with the result or decision, then provide only the detail needed to verify it. +- Do not create or retain a full session transcript. + +## Work Authorization + +- The default workflow is discussion first and explicit execution approval second. +- During discussion, perform only read-only investigation needed to understand the task and propose a concrete plan, unless the user prohibits inspection. +- Read-only investigation may include file inspection, code search, encoding checks, `git status`, `git diff`, `git log`, and sanitized official-documentation lookup. +- Before execution approval, do not edit files, install dependencies, run builds or tests, start services, connect to databases, or change local or external state. +- Before requesting approval, describe the intended scope, affected areas, validation plan, and material risks. +- Treat approval as limited to the presented scope. Pause and discuss again if the work materially expands. +- If the user explicitly requests immediate execution without prior discussion, the discussion gate may be skipped for the stated scope. +- Fast-track authorization does not implicitly authorize protected operations such as destructive commands, production changes, deployments, database mutations, Git publication, or external messages. + +## Local Development Environment + +- Primary OS: Windows 11. +- Primary shell: PowerShell. +- Use Git Bash only when the repository already depends on Bash or POSIX shell behavior. +- Prefer repository-provided wrappers and scripts over globally installed commands. +- Do not assume that GNU utilities, WSL, Docker, or a Unix-compatible shell are available unless the project profile confirms them. +- Detect Java, Node.js, .NET, Python, package-manager, and database-tool versions from repository configuration. +- Do not install or modify global toolchains as part of a project task. + +Preferred human-facing tools: + +- Classic ASP: Visual Studio Code +- Java and Spring Boot: IntelliJ IDEA +- C# and .NET: JetBrains Rider +- JavaScript, TypeScript, and Next.js: JetBrains WebStorm +- Python: JetBrains PyCharm +- Microsoft SQL Server: SQL Server Management Studio +- Other databases: JetBrains DataGrip + +- These preferences do not authorize launching or controlling a GUI application. +- Prefer IDE-independent commands that can also run in CI. +- Do not modify global IDE settings. +- Do not create or modify `.idea`, `.vscode`, workspace, or run-configuration files unless the approved task requires it. +- Preserve existing shared IDE configuration when it is already tracked. + +## PowerShell and Path Safety + +- Quote paths containing spaces, brackets, parentheses, Korean characters, or PowerShell metacharacters. +- Prefer `-LiteralPath` when operating on an exact filesystem path. +- Use project-relative paths in committed configuration and documentation. Do not commit machine-specific paths such as `D:\_____Dev\...`. +- Do not pass filesystem targets between PowerShell, `cmd.exe`, and Bash for destructive or recursive operations. +- Keep a filesystem operation within one shell from target resolution through execution. +- Before a recursive delete or move, resolve and verify every absolute target. +- Never use a drive root, workspace root, user profile, unresolved variable, wildcard, or broad glob as a recursive delete target. +- Prefer recoverable operations when practical. + +## Change Discipline + +- Preserve all existing user changes, including uncommitted and untracked work. +- Keep changes minimal but complete for the approved objective. +- Avoid unrelated cleanup, formatting, renaming, dependency upgrades, and architectural refactoring. +- Do not overwrite or revert unrelated changes. +- Stop and report when the requested change overlaps existing work in a way that cannot be handled safely. +- Prefer changing an authoritative source over editing generated output. +- Treat files marked as generated as read-only unless regeneration is part of the approved plan. +- Do not edit vendored dependencies, build outputs, caches, or generated clients unless explicitly required. +- Do not regenerate a broad set of files for a narrow change without first explaining the expected output scope. + +## Text Encoding and Korean Content Safety + +- Treat the existing file encoding, BOM state, and line-ending style as part of the file's contract. +- Preserve Korean comments, user-facing messages, error messages, identifiers, and documentation exactly unless the task explicitly requires changing them. +- Do not assume that garbled terminal output means the file itself is corrupted. Verify bytes and encoding before modifying suspicious text. +- Before editing an existing text file, determine its current encoding and BOM state when repository configuration does not already guarantee them. +- Do not convert encoding, add or remove a BOM, or normalize line endings as a side effect of an unrelated change. +- Avoid whole-file rewrites for small changes. +- Do not rewrite source files through `Get-Content | Set-Content`, `Out-File`, shell redirection, or another method whose encoding behavior is implicit. +- Do not use a patching or formatting tool on a non-UTF-8 file unless it is known to preserve that file's encoding. +- Treat a console display problem and an on-disk encoding problem as separate issues. +- After editing Korean text, inspect the diff for replacement characters (`�`), mojibake, unexpected escapes, BOM changes, and unrelated line-ending changes. +- Run `.agent/tools/check-encoding.ps1` when it is available and the change touches Korean text or a non-default encoding. +- If encoding cannot be identified confidently, stop before writing and report the affected file and evidence. +- For a new text file, follow repository configuration. If no rule exists, use UTF-8 without BOM. + +## Git Safety + +- Use `git status`, `git diff`, and `git log` for read-only investigation. +- Do not run `commit`, `push`, `pull`, `fetch`, `merge`, `rebase`, `reset`, `checkout`, `switch`, `stash`, `clean`, `tag`, or force operations unless that specific operation is explicitly approved. +- Source-edit approval does not include commit or push approval. +- Never amend an existing commit unless explicitly requested. +- Before an approved commit, show the intended files, validation results, and proposed commit message. +- Never push directly to a protected branch unless the user names the target branch and explicitly authorizes the push. + +## Dependencies and External Actions + +- Use the package manager, lockfile, and toolchain already selected by the repository. +- Do not install global packages. +- Do not add, remove, or upgrade a dependency unless it was included in the approved plan. +- Pause for approval if an unplanned dependency becomes necessary. +- Keep lockfiles synchronized with approved dependency changes. +- Do not deploy, publish packages, create releases, send messages or email, call business APIs, or modify external services unless explicitly requested. +- Never upload proprietary source code, internal documents, credentials, customer data, or database contents to an external service. +- Remove secrets and unnecessary internal identifiers from external search queries. + +## Database Safety + +- Treat writing or reviewing SQL as source code separately from executing SQL against a database. +- SQL files, migrations, schema proposals, and query drafts may be created within an approved source-change scope. +- Do not connect to a shared, staging, or production database without explicit authorization for that environment. +- Read-only queries against a non-local database also require authorization because results may contain sensitive data. +- Do not execute DDL, DML, stored procedures, migrations, administrative commands, or data-correction scripts against a non-disposable database without separate authorization for the exact target and operation. +- Source-change approval does not authorize migration execution. +- Use a disposable local or test database for approved validation only after verifying its identity and disposable nature. +- Never place credentials, connection strings, or sensitive query results in source files, logs, generated documents, or chat output. + +## Secrets and Sensitive Data + +- Never add credentials, tokens, passwords, private keys, connection strings, session identifiers, or production data to source control. +- Read sensitive files only when the approved task requires it and no safer source exists. +- Prefer inspecting configuration keys and schemas without displaying secret values. +- Never echo secrets into terminal output, chat responses, logs, diffs, generated documents, test fixtures, or screenshots. +- Redact sensitive values when reporting errors or command output. +- If a possible secret is discovered, do not repeat it. Report only its location, type, and recommended containment action. +- Do not rotate, revoke, copy, or otherwise modify credentials unless that exact action is explicitly authorized. + +## Validation + +- Discover supported build, test, lint, type-check, and formatting commands from repository files and project instructions. Do not invent commands. +- Include intended validation in the discussion-phase plan. +- After approved changes, run the narrowest relevant validation first, then broader checks when appropriate. +- Limit formatting to files within the approved scope. +- Do not run tests that require a shared database, production service, paid external API, or sensitive data unless separately authorized. +- Do not claim that a check passed unless it was executed successfully. +- If a check cannot be run, state the exact reason. +- Distinguish a current-change failure from a pre-existing failure or an undetermined failure. +- Do not fix unrelated failures without expanding the approved scope. +- Inspect the worktree after validation for unexpected generated files, formatting churn, encoding changes, or lockfile changes. + +## Artifacts and Session Records + +- Do not create full-session transcripts, automatic HTML copies, analysis reports, or extra documentation unless explicitly requested. +- Store durable information in the repository's existing documentation structure. +- Do not place generated reports or temporary analysis files in the repository root. +- Remove task-specific temporary files created by the current task after validation when removal is safe. + +## Completion Report + +When implementation is complete, report in Korean: + +- what changed and why; +- the main affected files or components; +- validation commands actually executed and their results; +- checks not executed and the reason; +- remaining risks, assumptions, or follow-up work; +- database, deployment, dependency, encoding, and compatibility impact when applicable. + +- Do not report completion while required validation is failing or known encoding corruption is unresolved. +- Keep the report concise and do not include a full session transcript. + +## Internal Service Project Rules + +- Internal-only usage does not reduce security, privacy, compatibility, or validation requirements. +- Preserve authentication, authorization, role boundaries, auditability, and personal-data protections. +- Identify affected user workflows before changing visible behavior. +- Treat Frontend and Backend repositories as separate deployable systems with an explicit API contract between them. +- Coordinate request, response, authentication, error, and versioning changes across both sides when the approved scope includes both repositories. +- Do not silently require a simultaneous Frontend and Backend deployment. +- Prefer backward-compatible transitions when deployments may occur independently. +- Include migration and rollback considerations for database, API, and configuration changes. +- Do not modernize legacy code as an unrelated side effect. +- Apply Classic ASP text-safety rules only when the project profile declares the `classic-asp` stack. +- Do not access or modify production data merely because the service is internal. + +## Classic ASP + +- Prioritize behavior preservation. Do not modernize syntax, includes, data access, error handling, or page structure outside the approved scope. +- Trace the full include chain and relevant application/session/configuration dependencies before changing shared ASP behavior. +- Preserve `Response.CodePage`, `Response.CharSet`, page directives, response headers, and the existing browser/server encoding contract. +- Parameterize ADO commands and preserve the expected command type, parameter order, data types, sizes, directions, result sets, and transaction behavior. +- Close and release recordsets, commands, connections, streams, and other COM resources on every applicable path. +- Preserve the established `On Error Resume Next` and error propagation pattern; do not suppress newly introduced failures. + +### Legacy Text File Safety + +- Treat each existing Classic ASP text file's byte encoding, BOM state, and line endings as part of its contract. +- Detect those properties before editing and preserve them exactly unless an encoding conversion is explicitly approved. +- Do not assume UTF-8. Existing files may use UTF-8 with or without BOM, EUC-KR/CP949, or another legacy encoding. +- Keep Korean comments, literals, SQL, HTML, JavaScript, and error messages byte-safe. Stop if the source encoding cannot be identified confidently. +- Avoid formatters or bulk rewrites that normalize encoding or line endings across the file. +- After editing, run the harness encoding check and inspect the diff for replacement characters, mojibake, unexpected BOM changes, or whole-file churn. + +## Microsoft SQL Server + +- Use T-SQL syntax and behavior only for data sources whose declared engine is `mssql`. +- Preserve the configured SQL Server version, database and schema names, collation, naming, migration, and access conventions. +- Parameterize values. Do not build SQL by concatenating untrusted input. +- Preserve Unicode behavior and use the repository's established `nvarchar`/`nchar` and parameter conventions where Korean or other Unicode text is possible. +- Treat stored-procedure parameters, result sets, return values, transaction behavior, and error behavior as public contracts. +- Consider indexes and actual execution characteristics for changed filters, joins, ordering, grouping, and pagination. +- Do not introduce MySQL or other dialect syntax into MSSQL paths. +- Keep read-only legacy integrations read-only. A source-code change approval authorizes SQL analysis and script drafting only; execution requires separate explicit approval and the declared data-source access level. + +## Planned Migration + +- Treat the current stack and production behavior as authoritative until an explicit migration task and slice are approved. +- Do not begin a partial migration while handling an unrelated feature, fix, review, or refactor. +- Before migration work, document the relevant baseline: routes, APIs, authentication, authorization, state, data contracts, environment variables, build, deployment, operations, and user-visible behavior. +- Define small staged slices with acceptance criteria, compatibility requirements, validation, rollout, and rollback for each slice. +- Keep migrated and non-migrated areas interoperable for as long as both remain active. +- Apply target-stack conventions only inside the approved slice and shared boundaries that must change with it. +- Establish behavior equivalence with representative checks before removing the previous implementation. +- Separate intentional product or behavior changes from framework-only migration changes so each can be reviewed independently. +- For standalone React applications, the default planned target is Next.js with TypeScript unless the project profile explicitly declares another approved target. + +## KON-KIWI Repository Rules + +### Repository Role and Twin-Project Relationship + +- This is a legacy Classic ASP application maintained alongside `KON`; the two repositories are near twins whose main differences are presentation and styling. +- Preserve current routes, includes, sessions, authentication, authorization, form fields, redirects, uploads, downloads, and MSSQL behavior while the application remains in service. +- Before changing shared-looking behavior, compare the corresponding KON implementation and determine whether the change belongs in both repositories or only this one. +- Do not copy a change across the pair blindly. Preserve intentional branding, layout, CSS, asset, configuration, customer, and deployment differences. +- Keep maintenance and small approved feature work narrowly scoped. Do not modernize unrelated business areas or shared include trees as a side effect. + +### Encoding and File Safety + +- Treat Classic ASP, include, script, and configuration files as potentially CP949/EUC-KR with CRLF. Verify each touched file's encoding, BOM state, line endings, response code page, and charset behavior before and after editing. +- Never run a repository-wide UTF-8 conversion, formatter, or line-ending normalization. Inspect byte-level diffs and Korean comments, messages, labels, and data after every approved text change. +- Treat existing connection settings and operational configuration as sensitive legacy material. Do not echo their values into chat, logs, fixtures, generated documentation, or completion reports, and do not alter them without explicit task scope. + +### Runtime and Repository Data + +- `Project`, `log`, `ProjectUpload`, `uploadFile`, `WebProject`, `_ServerLog`, and `Files` retain only `.gitkeep`; do not add runtime contents from these directories to Git. +- `store` is intentionally versioned. Preserve its tracked contents and do not add it to ignore rules or remove it as cleanup without explicit approval. +- Do not modify uploaded files, generated projects, logs, or runtime artifacts during analysis or validation. + +### Data and Migration Direction + +- Trace include chains and shared DB helpers before changing SQL, authentication, authorization, sessions, uploads, or file handling. +- Parameterize new or changed values while preserving ADO parameter order, types, result shapes, transactions, null behavior, and ordering. +- The long-term direction is staged migration to a Spring Boot backend and Next.js/TypeScript frontend. For now, record relevant migration observations briefly and prioritize safe legacy maintenance. + +### Harness and Verification + +- `AGENTS.md` and `CLAUDE.md` are generated. Edit `.agent/profile.yml` or `.agent/project.md`, then recompose instead of editing generated files. +- Do not start IIS, connect to a real database, send external requests, or mutate production-like data during validation without separate approval. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..43c994c --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md