AI-Lab-for-Cities-at-Harvard/civic-skill-exchange

스킬 현지화

결과물

독립적으로 작동하는 하나의 아티팩트와 그 생성 기록.

<skill-name>/                 일반 스킬. 그대로 실행됨.
  SKILL.md                    {{슬롯}}이나 TODO 없이 값이 채워져 있음
  references/…  scripts/…     전체적으로 동일하게 적용됨
<org>.context.yml             채워진 컨텍스트. 나중에 다시 현지화할 때 보관.
<org>.profile.yml             조직 전체 응답. 향후 모든 스킬에 재사용됨.
LOCALIZE-NOTES.md             유도된 값, 질문한 값, 기본값 처리, 미확인 값 기록

현지화된 스킬은 실행 시점에 컨텍스트 파일을 읽지 않습니다. 값은 본문에 직접 기록됩니다. 실행 시마다 컨텍스트를 로드하여 자신의 필드 이름을 알아내야 하는 스킬은 호출될 때마다 비용을 지불하고, 파일이 이동하면 혼란스럽게 실패합니다. 컨텍스트는 결정의 기록이지, 런타임 종속성이 아닙니다.

파일 형식은 references/contract.md를, 질문 전에 알아야 할 사항은 references/asking.md를, 결과물 반환 전 확인 사항은 references/verify.md를 읽으십시오.

중요한 실패 지점

질문의 개수가 아닙니다. 채택자가 답변할 수 없는 질문입니다.

데이터 세트 식별자와 스키마 필드 이름을 읍면동 공무원에게 묻는 스킬은 천천히 채워지지 않습니다. 그냥 버려집니다. 그리고 그 포기는 디자인 결함이 아닌 무관심처럼 보입니다. 이것이 교환이 규모에 맞게 작동하는 것을 막는 원인이며, 이는 채택자의 문제가 아니라 질문의 속성입니다.

따라서: 유도할 수 있는 것은 유도하고, 스킬에 대해 묻기보다 조직에 대해 질문하며, 조직이 이미 제공한 답변이 이후 채택하는 모든 스킬에 재사용되도록 하십시오.

두 번째 실패는 더 조용합니다. 그럴듯한 잘못된 값으로 채워진 슬롯은 실행되고 숫자를 반환하지만 틀린 결과를 내는 스킬을 만듭니다. 확인되지 않은 값을 exact: true 슬롯에 절대 기록하지 마십시오. 막히는 빈칸은 복구 가능하지만, 오해를 불러일으키는 채움은 그렇지 않습니다.

단계

1. 다른 어떤 것보다 먼저 contract_version을 확인하십시오. 컨텍스트 파일의 첫 번째 키입니다. references/contract.md의 버전과 비교하십시오.

일치하는 것이 일반적인 경우입니다. 계속 진행하고 이에 대해 언급하지 마십시오. 파일이 이전 버전인 경우, 변경 로그를 기준으로 마이그레이션하고 어떤 항목이 변경되었는지 기록하십시오. 파일이 이 스킬이 이해하는 것보다 최신인 경우, 중단하십시오. 어떤 슬롯도 채우지 마십시오. 알 수 없는 호환성 변경은 파일의 모든 값이 잘못 읽힐 수 있음을 의미하며, 잘못 읽힌 값은 실행되어 숫자를 반환하는 스킬에서 그럴듯한 잘못된 값이 됩니다. 차이점을 명시하고 최신 localize-skill을 요청하십시오.

contract_version이 없는 경우, 1이라고 가정하지 마십시오. 버전 관리 이전에 작성된 파일은 오래된 형태가 아니라 알 수 없는 형태를 가집니다. 무엇이 그것을 생성했는지 질문하십시오.

2. scope를 읽고, 그것을 말로 표현하십시오. 어떤 질문보다 먼저, 채택자에게 스킬이 어떤 계층에서 작동하며 얼마나 일반화되었는지 한 문장으로 알려주십시오: 이것은 도시를 위해 작성되었으며 다른 미국 도시 및 타운을 위해 일반화되었습니다.

채택자가 그 범위 안에 속하는지 여부는 조회가 아니라 판단이므로, 테스트하지 말고 그들에게 판단을 맡기십시오. 범위 밖의 채택자는 채우기보다 다시 일반화해야 합니다: 슬롯만이 이식 가능하게 만들어진 유일한 것이며, 그대로 남겨진 것은 여기서 보이지 않습니다. 그 슬롯들을 채우면 완성된 것처럼 보이지만, 그들이 가지고 있지 않은 국가, 법률 시스템 또는 정부 형태를 조용히 가정하는 스킬이 됩니다.

유지된 값이 그들에게 현지처럼 보인다면(예: 와드 수준 스킬의 도시 이름), 이는 범위가 작동하고 있는 것이지 실수가 아닙니다. 채택자가 그것을 고치려고 시도하기 전에 그렇게 말하십시오.

3. 이미 알려진 것을 로드하십시오. 어떤 질문보다 먼저, 현재 가지고 있는 답변을 수집하십시오:

• <org>.profile.yml: 이 조직이 이전에 스킬을 채택한 적이 있다면. 관할권, 승인 공무원, 오픈데이터 포털, 회계연도는 그들이 채택할 모든 스킬에서 동일합니다. 두 번 묻는 것은 교환소가 두 번째 스킬에서 사람들을 잃는 방법입니다.
• 다른 슬롯이 암시하는 값. 포털 기본 URL과 데이터 세트 식별자는 두 개의 독립적인 질문이 아닙니다.
• scope에 의해 결정된 기본값 — 국가, 통화, 우편 형식, 법정 체계 — 이는 계층과 범위로 이미 고정됩니다.

4. 유도할 수 있는 것을 유도한 다음, 확인하십시오. 공개 소스가 있는 값(데이터 세트 식별자, 스키마 필드 이름, 포털 엔드포인트, 부서 이름)의 경우 조회하여 제안하십시오. 311 오픈 날짜 열이 case_opened_dt인 것 같습니다. 맞습니까? 는 누구나 답할 수 있는 질문입니다. 311 오픈 날짜 열이 무엇입니까? 는 거의 아무도 답할 수 없는 질문입니다.

유도된 값을 확인하는 것도 질문이지만, 다른 종류입니다: 회상이 아닌 인식을 요구하며, 인식은 데이터를 구축하지 않은 사람이 사용할 수 있게 만드는 것입니다. 유도는 exact: true 값에 대한 확인을 제거하지 않습니다. 부담을 옮기는 것이지, 확인을 없애는 것이 아닙니다.

5. 나머지는 한 번에 질문하십시오. 한 번에, 똑똑 떨어뜨리지 말고. 채택자가 가장 잘 아는 순서로 정렬하십시오: 조직 먼저, 데이터 나중에. 2단계에서 이미 답변된 것은 건너뛰고, 이 채택자가 사용하지 않을 스킬 분기의 슬롯도 건너뛰십시오. 선택적 슬롯을 성급하게 묻는 것은 필수 슬롯과 구분할 수 없습니다.

질문을 exact에 맞추십시오. false인 경우, 기본값을 제공하고 대략적인 답변이 괜찮다고 말하십시오; 비공식적으로 처리합니다, 주변에 있는 사람이요 라는 것은 실제 답변입니다. true인 경우, 값이 정확히 일치해야 하며 그 이유를 말하십시오. 그래야 추측이 선택 사항이 아니라는 것을 인식할 수 있습니다. references/asking.md에 효과적인 형태가 있습니다.

6. 값을 기록하십시오. 본문 전체에 대체하십시오: 본문, 참조, 스크립트, 파일 이름, 주석. 그런 다음 프론트매터를 복원하십시오: description, civic.use-when, civic.avoid-when은 컨텍스트의 조직별 버전을 가져옵니다. 에이전트는 컨텍스트가 로드되기 전에 이것들을 읽고, 중립적인 것은 지역 요청에 대해 작동하지 않을 것이기 때문입니다.

civic.localization: localized 및 civic.jurisdiction을 조직으로 설정하십시오. 스킬 디렉토리에서 context.template.yml을 제거하십시오. 최종 결과물은 누군가 이 조직을 위해 스킬을 작성한 것처럼 보여야 합니다. 왜냐하면 이제 그렇기 때문입니다.

7. 기록을 작성하십시오. 모든 값과 출처(프로필, 유도, 질문, 기본값)를 포함한 <org>.context.yml. 조직 전체에 적용되는 사항으로 업데이트된 <org>.profile.yml. 확인 없이 기본값 처리된 것, 사용되지 않아 건너뛴 것, 채택자가 확신하지 못한 것에 대한 LOCALIZE-NOTES.md. 출처는 나중에 인터뷰를 다시 하지 않고도 잘못된 숫자를 감사할 수 있게 해줍니다.

8. 반환하기 전에 검증하십시오. references/verify.md. 여전히 {{slot}} 또는 TODO를 포함하는 스킬은 완료되지 않은 것이며, 값이 확인되지 않은 스킬은 명백히 완료되지 않은 것보다 더 나쁩니다.

완료 전 확인 사항

• 컨텍스트 파일의 contract_version이 확인되었으며, 이 스킬이 이해하는 것보다 최신 파일에서 슬롯이 채워지지 않았습니다.
• 스크립트, 참조, 파일 이름 및 주석을 포함하여 어디에도 {{placeholder}} 또는 TODO가 남아 있지 않습니다.
• 모든 exact: true 값은 사람에 의해 확인되었거나 조직 자체 시스템에서 가져왔습니다. 추론되어 조용히 기록된 것은 없습니다.
• description, civic.use-when, civic.avoid-when은 조직을 명시하며 지역 요청에 대해 작동합니다.
• 스킬은 컨텍스트 파일을 읽지 않고 실행됩니다.
• LOCALIZE-NOTES.md는 확인되지 않거나 기본값 처리된 모든 값을 나열하며, 채택자가 해당 목록을 보았습니다.
• <org>.profile.yml은 조직 전체 정보를 포함하여, 다음 스킬이 질문을 덜 하도록 합니다.